Webhooks

Webhooks let you receive notifications when payout or banking activity happens — without polling. You subscribe a callback URL to an event type, and Karat sends an HTTP POST to that URL whenever the event occurs.

Discover available events

Call GET /events to list the event types you can subscribe to.

Create a subscription

Call POST /events/subscription with the event_name and your callback_url. The response includes a secret — store it to verify future deliveries.

Acknowledge deliveries

Respond with a 2xx status so Karat knows the event was received.

curl https://payouts.api.trykarat.com/events/subscription \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "payout.updated",
    "callback_url": "https://example.com/api/webhooks/callback"
  }'

Secret generation

Karat generates a unique signing secret when you create a subscription. The secret is returned only once in the create subscription response — store it securely so you can verify deliveries.

Handshake verification

When creating a subscription, the API verifies ownership of the callback URL by performing a challenge-response handshake. Your server must handle this before the subscription is accepted. The API sends a POST request to your callback_url with a JSON body:

{
  "type": "url_verification",
  "challenge": "a3f8b2e..."
}

Your server must respond within 30 seconds with HTTP status 200 and a JSON body echoing the challenge:

{
  "challenge": "a3f8b2e..."
}

If verification succeeds, the subscription is created. If it fails, the API returns a 400 error with one of these messages:

Message	Cause
`Callback URL verification failed: could not reach the URL`	The URL was unreachable, timed out, or the connection was refused
`Callback URL verification failed: received status {code}`	Your server responded with a non-`2xx` status code
`Callback URL verification failed: invalid JSON response`	The response body was not valid JSON
`Callback URL verification failed: challenge mismatch`	The `challenge` value in the response did not match the one sent

Event types

Event	When it fires
`payout.updated`	A payout’s status changes
`tax_form.created`	A recipient completes a tax form
`recipient.updated`	A recipient reaches an onboarding milestone
`transaction.pending`	A pending entry was created.
`transaction.updated`	An existing pending or posted record’s exposed fields changed.
`transaction.posted`	A posted entry was created, possibly without a preceding pending entry.
`transaction.pending_completed`	A pending entry is no longer active. Remove it from your pending set. Completion does not imply settlement or guarantee a posted transaction.

Payload

Every delivery shares the same envelope — id, event, created_at, subscription_id, and an event-specific data object.

`payout.updated`

{
  "id": "a2b6f9c8-7d5f-4c2b-bd7a-1c2f9b5c44b9",
  "event": "payout.updated",
  "created_at": "2026-03-02T12:34:56Z",
  "subscription_id": "7a6b5c4d-3e2f-1a0b-9c8d-7e6f5a4b3c2d",
  "data": {
    "id": "8e0c87c1-948c-4e57-9b48-9b5ab4c0d7e8",
    "status": "created",
    "reason": null,
    "reference_id": "6ae5b965-ad32-4d21-bff9-f1e661f05ca3",
    "payout_intent_id": "05545ccf-0798-4661-8b36-2ad7c0bf5375",
    "date": "2025-09-30T14:59:37.055Z"
  }
}

`tax_form.created`

{
  "id": "78ce3584-0761-40ab-bcb1-ef7c5bffe095",
  "event": "tax_form.created",
  "created_at": "2026-03-10T23:45:07.878Z",
  "subscription_id": "48582de1-c2fb-4fd3-bdf3-39a7138d1164",
  "data": {
    "id": "ffc96bee-3ce9-4bfc-a436-c08cc2a3d33e",
    "recipient": {
      "id": "db783652-823b-46f8-88e2-93ae37442232",
      "firstName": "John",
      "lastName": "Doe",
      "nickname": null
    },
    "createdAt": "2026-03-10T23:45:07.868Z",
    "url": "https://url.com/pdf"
  }
}

`recipient.updated`

Sent as a recipient moves through onboarding. The status field carries the milestone:

`status`	Meaning
`onboarding_started`	The recipient opened their onboarding invitation
`tax_info_collected`	The recipient’s tax information was collected
`onboarding_completed`	The recipient finished onboarding

Each milestone is sent at most once per onboarding invitation — repeating a step (for example, re-signing a tax form) does not produce another event. The tax_info_collected event is never sent for recipients you configured with tax collection disabled; those recipients go straight from onboarding_started to onboarding_completed.

{
  "id": "6dabe27e-7172-469a-b32e-e4dbcb7fdf90",
  "event": "recipient.updated",
  "created_at": "2026-08-07T03:05:03.686Z",
  "subscription_id": "0645b8bf-f1a6-461b-8288-0d75452cd8cb",
  "data": {
    "recipient_id": "af93361d-f297-4786-a8b7-4cce8fe8bdc9",
    "first_name": "John",
    "last_name": "Doe",
    "nickname": null,
    "business_type": "individual",
    "status": "tax_info_collected",
    "date": "2026-08-07T03:05:00.045Z"
  }
}

first_name, last_name, and nickname are nullable. date is the ISO-8601 timestamp of when the milestone occurred. business_type reports whether the recipient registered as an individual or an entity. It is null until the recipient’s tax information has been collected and shared with you — expect null on onboarding_started and a value from tax_info_collected onward. It matches profile.businessType on the recipients endpoints; sandbox recipients always report individual.

Transaction events

Transaction subscriptions cover eligible open, unlocked operational checking accounts belonging to your API key’s organization. They are not limited to payouts created through the API. Use data.transaction.accountId to identify the account; there is no account filter when creating a subscription. Create a separate subscription for each transaction event type you need:

curl https://payouts.api.trykarat.com/events/subscription \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "transaction.posted",
    "callback_url": "https://example.com/api/webhooks/callback"
  }'

The same callback handshake, signing secret, signature headers, and acknowledgment rules above apply. The transaction object follows the account transactions contract. Amounts are signed minor units (USD cents). Pending and posted records have separate IDs. relatedTransactionId is a provider association when known, not a guaranteed match; do not match by amount or description.

`transaction.pending`

{
  "id": "a1111111-1111-4111-8111-111111111111",
  "event": "transaction.pending",
  "created_at": "2026-10-05T10:00:01Z",
  "subscription_id": "7a6b5c4d-3e2f-4a0b-9c8d-7e6f5a4b3c2d",
  "data": {
    "revision": "1",
    "occurredAt": "2026-10-05T10:00:00Z",
    "transaction": {
      "id": "pending_transaction_example",
      "accountId": "4f266e59-5dae-49f7-9ef9-9bdf6d2b7c86",
      "amount": -12500,
      "currency": "USD",
      "status": "pending",
      "transactionAt": "2026-10-01T10:00:00Z",
      "postedAt": null,
      "timestampSource": "provider",
      "description": "Outgoing transfer hold",
      "type": "ach_transfer_intention",
      "relatedTransactionId": null
    }
  }
}

`transaction.updated`

{
  "id": "a2222222-2222-4222-8222-222222222222",
  "event": "transaction.updated",
  "created_at": "2026-10-05T10:00:01Z",
  "subscription_id": "7a6b5c4d-3e2f-4a0b-9c8d-7e6f5a4b3c2d",
  "data": {
    "revision": "2",
    "occurredAt": "2026-10-05T10:00:00Z",
    "transaction": {
      "id": "pending_transaction_example",
      "accountId": "4f266e59-5dae-49f7-9ef9-9bdf6d2b7c86",
      "amount": -15000,
      "currency": "USD",
      "status": "pending",
      "transactionAt": "2026-10-01T10:00:00Z",
      "postedAt": null,
      "timestampSource": "provider",
      "description": "Outgoing transfer hold",
      "type": "ach_transfer_intention",
      "relatedTransactionId": null
    }
  }
}

`transaction.posted`

{
  "id": "a3333333-3333-4333-8333-333333333333",
  "event": "transaction.posted",
  "created_at": "2026-10-05T10:00:01Z",
  "subscription_id": "7a6b5c4d-3e2f-4a0b-9c8d-7e6f5a4b3c2d",
  "data": {
    "revision": "1",
    "occurredAt": "2026-10-05T10:00:00Z",
    "transaction": {
      "id": "transaction_example",
      "accountId": "4f266e59-5dae-49f7-9ef9-9bdf6d2b7c86",
      "amount": -12500,
      "currency": "USD",
      "status": "posted",
      "transactionAt": "2026-10-01T10:00:00Z",
      "postedAt": "2026-10-01T10:00:00Z",
      "timestampSource": "provider",
      "description": "Outgoing transfer",
      "type": "account_transfer_intention",
      "relatedTransactionId": null
    }
  }
}

`transaction.pending_completed`

{
  "id": "a4444444-4444-4444-8444-444444444444",
  "event": "transaction.pending_completed",
  "created_at": "2026-10-05T10:00:01Z",
  "subscription_id": "7a6b5c4d-3e2f-4a0b-9c8d-7e6f5a4b3c2d",
  "data": {
    "revision": "3",
    "occurredAt": "2026-10-05T10:00:00Z",
    "transaction": {
      "id": "pending_transaction_example",
      "accountId": "4f266e59-5dae-49f7-9ef9-9bdf6d2b7c86",
      "amount": -15000,
      "currency": "USD",
      "status": "complete",
      "transactionAt": "2026-10-01T10:00:00Z",
      "postedAt": null,
      "timestampSource": "provider",
      "description": "Outgoing transfer hold",
      "type": "ach_transfer_intention",
      "relatedTransactionId": null
    }
  }
}

transaction.updated can contain either a pending or posted record; the example shows a pending amount update. transaction.posted can arrive without a preceding pending event. transaction.pending_completed means the hold is no longer active, not that it settled. Remove it from your pending set. Its status: "complete" is only delivered by this event and never appears in the active-pending endpoint results. A completion event may be your first notification for a pending entry created before your subscription. A released hold need not produce a posting; returns are separate movements.

Ordering, retries, and recovery

data.occurredAt is when Karat captured the change, not its provider booking time.
data.revision is a positive decimal string that increases independently per transaction ID. Compare it as an integer, not lexicographically, and never compare revisions between different transactions.
Delivery is at least once and may arrive out of order. Deduplicate using the envelope id; retries retain the original payload and ID. Only apply a revision newer than the last one stored for that transaction.
Keep the completion revision after removing a pending entry, so a delayed pending update cannot restore it.
Only subscriptions that existed when the change was captured receive that change. New subscriptions do not receive a historical backfill. Deleted subscriptions and accounts that are no longer eligible receive no new dispatch.
Delivery may fail permanently after retries. Use the transactions endpoint to backfill posted records, refresh the complete active-pending set, and periodically reconcile after downtime or delivery failures.

Verify webhook signatures

Every delivery is signed so you can confirm it came from Karat. Verify the signature before processing the payload. Each request includes these headers:

Header	Description
`X-Karat-Signature`	The signature, in the format `v1=<base64>`.
`X-Karat-Webhook-Timestamp`	Unix epoch seconds when the event was sent.
`X-Karat-Subscription-Id`	The subscription the event belongs to — use it to look up the right `secret`.
`X-Karat-Webhook-Id`	Unique delivery ID, for deduplication.

The signature is an HMAC-SHA256 of timestamp + "." + raw_body, keyed with your subscription secret, then base64-encoded:

signed_payload   = X-Karat-Webhook-Timestamp + "." + raw_request_body
signature_base64 = base64(HMAC_SHA256(secret, signed_payload))

To verify a delivery:

Look up the secret

Use X-Karat-Subscription-Id to find the secret you stored when creating the subscription.

Check the timestamp

Reject deliveries where X-Karat-Webhook-Timestamp is outside a ±300 second window to protect against replays.

Recompute and compare

Recompute the signature from the raw request body and compare it to the value in X-Karat-Signature using a constant-time comparison.

Deduplicate

Use X-Karat-Webhook-Id (and the id in the body) to ignore duplicate deliveries.

import crypto from "crypto";

function verifyKaratWebhook({ headers, rawBody }, secret) {
  const timestamp = headers["x-karat-webhook-timestamp"];

  // Replay protection: reject deliveries older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  // Build the signed payload from raw bytes so the body is never re-encoded.
  const signedPayload = Buffer.concat([
    Buffer.from(`${timestamp}.`),
    Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody),
  ]);
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("base64");

  const provided = (headers["x-karat-signature"] ?? "").replace(/^v1=/, "");
  const a = Buffer.from(expected);
  const b = Buffer.from(provided);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Compute the signature over the exact raw bytes you received, before any JSON parsing or re-serialization — reformatting the body will change the signature. If verification fails, return a non-2xx response and do not process the event.

Delivery

Deliveries are sent asynchronously and retried on failure.
Always return a 2xx response quickly; do heavy processing out of band.

Manage subscriptions

List your subscriptions with GET /events/subscription.
Remove one with DELETE /events/subscription/{subscription_id}.

Get started

API reference

Secret generation

Handshake verification

Event types

Payload

`payout.updated`

`tax_form.created`

`recipient.updated`

Transaction events

`transaction.pending`

`transaction.updated`

`transaction.posted`

`transaction.pending_completed`

Ordering, retries, and recovery

Verify webhook signatures

Delivery

Manage subscriptions

Get started

API reference

​Subscribe to an event

​Secret generation

​Handshake verification

​Event types

​Payload

​payout.updated

​tax_form.created

​recipient.updated

​Transaction events

​transaction.pending

​transaction.updated

​transaction.posted

​transaction.pending_completed

​Ordering, retries, and recovery

​Verify webhook signatures

​Delivery

​Manage subscriptions

Subscribe to an event

Secret generation

Handshake verification

Event types

Payload

`payout.updated`

`tax_form.created`

`recipient.updated`

Transaction events

`transaction.pending`

`transaction.updated`

`transaction.posted`

`transaction.pending_completed`

Ordering, retries, and recovery

Verify webhook signatures

Delivery

Manage subscriptions