Webhook management

Kashier's webhook management module lets you configure multiple named webhooks per merchant instead of a single fixed URL. Each webhook is scoped to a mode (test or live) and subscribed to a specific set of event types, so different endpoints can receive different slices of your traffic — for example, a production endpoint that only cares about refund and transfer status changes, and a separate test endpoint your staging environment listens to.

This page covers creating and managing webhooks, looking up delivery records for a transaction or transfer, resending a delivery, and sending a test payload to verify an endpoint is reachable. For the shape of the event payload itself and signature verification, see Webhook payloads and the Webhooks guide.

All endpoints on this page are merchant-authenticated — send your secret key in the Authorization header, the same as everywhere else in the API.

If you used the old single-URL webhook

If your account was set up with Kashier's older single stored webhook URL, there's nothing to re-create. That URL is migrated into webhook management for you, so List your webhooks returns it as a webhook named Legacy webhook, subscribed to every event type, with isActive carrying over whether the old webhook was enabled and mode derived from your account's current mode. It keeps receiving exactly what it received before the migration.

From there it's an ordinary webhook. Rename it, narrow its events to the ones you actually handle, add custom headers, or switch it off with Update a webhook. If you want separate test and live destinations, create a second webhook for the other mode rather than flipping this one's mode back and forth.

List your webhooks

Returns every webhook configured for your merchant, across both modes.

Full parameter and response reference → List your webhooks.

curl --location 'https://test-api.kashier.io/v2/webhooks' \
  --header 'Authorization: YOUR_TEST_SECRET_KEY'

Headers

Response

[
  {
    "_id": "66a1f2c3e4b0a1234567890a",
    "merchantId": "MID-10293",
    "name": "Orders production endpoint",
    "url": "https://shop.example.com/kashier/webhook",
    "headers": {
      "X-Shop-Token": "whsec_live_abc123",
      "X-Env": "production"
    },
    "events": ["pay", "refund", "void", "TRANSFERRED"],
    "mode": "live",
    "isActive": true,
    "createdAt": "2026-06-22T12:00:00.000Z",
    "updatedAt": "2026-06-22T12:00:00.000Z"
  }
]

Create a webhook

Creates a new webhook for your merchant.

Full parameter and response reference → Create a webhook.

Body parameters

events accepts any of the following values:

The mixed casing is deliberate — each value matches the producing service's own literal, so transaction operations are lowercase and transfer statuses uppercase. Send them exactly as written.

curl --location 'https://test-api.kashier.io/v2/webhooks' \
  --header 'Authorization: YOUR_TEST_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Orders staging endpoint",
    "url": "https://your-website.com/kashier-webhook",
    "headers": {
      "X-Shop-Token": "replace-with-your-own-token",
      "X-Env": "staging"
    },
    "events": ["pay", "refund", "void", "TRANSFERRED"],
    "mode": "test",
    "isActive": true
  }'

For a production webhook, send the same body with "mode": "live" to https://api.kashier.io/v2/webhooks using your live secret key — keep mode and the host you call in step rather than creating a live webhook from the test host.

Headers

Response

Returns the created webhook, in the same shape as an entry in List your webhooks.

Update a webhook

Updates an existing webhook. Send only the fields you want to change.

Full parameter and response reference → Update a webhook.

Body parameters

Same fields as Create a webhook — name, url, headers, events, mode, isActive — all optional on update. The https-only URL rule applies here too. Changing mode re-checks the 5-per-mode limit against the target mode.

curl --location --request PUT 'https://test-api.kashier.io/v2/webhooks/:webhookId' \
  --header 'Authorization: YOUR_TEST_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "isActive": false
  }'

Headers

Response

Returns the updated webhook, in the same shape as an entry in List your webhooks.

Delete a webhook

Removes a webhook. There's no undo — deliveries already recorded against it stay visible in delivery records.

Full parameter and response reference → Delete a webhook.

curl --location --request DELETE 'https://test-api.kashier.io/v2/webhooks/:webhookId' \
  --header 'Authorization: YOUR_TEST_SECRET_KEY'

Headers

Get delivery records for a transaction

Returns the delivery log for a given transaction — every webhook attempt made for it, across all your configured webhooks, plus any per-session webhook you passed directly on that transaction.

Full parameter and response reference → Get delivery records for a transaction.

curl --location 'https://test-api.kashier.io/v2/webhooks/records/transaction/:transactionId' \
  --header 'Authorization: YOUR_TEST_SECRET_KEY'

Headers

Response

{
  "success": true,
  "body": [
    {
      "resourceType": "transaction",
      "resourceId": "TX-249893963",
      "webhookId": "66a1f2c3e4b0a1234567890a",
      "eventType": "pay",
      "mode": "live",
      "url": "https://shop.example.com/kashier/webhook",
      "status": "delivered",
      "attempts": 1,
      "payload": { "...": "allow-listed fields only" },
      "responses": [
        { "status": 200, "body": "OK", "date": "2026-06-22T12:00:01.000Z" }
      ],
      "isServerWebhook": false,
      "isTest": false,
      "createdAt": "2026-06-22T12:00:00.000Z",
      "updatedAt": "2026-06-22T12:00:01.000Z"
    }
  ]
}

Get delivery records for a transfer

Same records lookup as above, scoped to a transfer instead of a transaction.

Full parameter and response reference → Get delivery records for a transfer.

curl --location 'https://test-api.kashier.io/v2/webhooks/records/transfer/:transferId' \
  --header 'Authorization: YOUR_TEST_SECRET_KEY'

Headers

Response

Same shape as Get delivery records for a transaction, except resourceType is transfer, resourceId is the transfer ID, and eventType is one of the transfer status values (INITIATED, IN_TRANSIT, TRANSFERRED, FAILED).

Resend a delivery

Re-sends a previously recorded delivery — the original stored request, byte-for-byte, including its original signature — to the same URL. Useful after fixing an endpoint that was down or returning errors. The outcome is written to a new record; the original record is never modified, so your delivery history stays intact.

A record can be resent from any status, including delivered. The endpoint takes no request body — everything it needs comes from recordId in the path.

Full parameter and response reference → Resend a delivery.

curl --location --request POST 'https://test-api.kashier.io/v2/webhooks/records/:recordId/resend' \
  --header 'Authorization: YOUR_TEST_SECRET_KEY'

Headers

Response

{
  "recordId": "66a20a1ce4b0a1234567891b",
  "clonedFromRecordId": "66a1f2c3e4b0a1234567890c",
  "status": "delivered",
  "attempts": 1,
  "lastResponseStatus": 200
}

Test a webhook

Sends a signed sample payload to a webhook's configured URL so you can confirm the endpoint is reachable and your signature verification works — without waiting for a real event. The test delivery is recorded like any other delivery, but flagged isTest: true so it's distinguishable in your delivery history.

Full parameter and response reference → Test a webhook.

curl --location --request POST 'https://test-api.kashier.io/v2/webhooks/:id/test' \
  --header 'Authorization: YOUR_TEST_SECRET_KEY'

Headers

Response

{
  "success": true,
  "statusCode": 200,
  "responseBody": "OK",
  "latencyMs": 184
}

Next steps