Payment webhooks

Tabby Webhooks are HTTPS callbacks that notify you about payment-related and token-related events. You register a URL once, and Tabby sends a POST request to it whenever an event related to your account occurs — even when the customer never returns to your site. This makes webhooks the most reliable way to catch authorized payments.

How They Work

Register a webhook for each merchant_code + secret key pair — the merchant code is passed in the X-Merchant-Code header (required):

curl -X POST https://api.tabby.ai/api/v1/webhooks \
  -H "Authorization: Bearer sk_test_..." \
  -H "X-Merchant-Code: your_merchant_code" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-store.com/tabby/webhook",
    "header": { "title": "X-Auth-Key", "value": "your_random_signing_secret" }
  }'

The environment is determined by the key you register with: a production key (sk_...) registers webhooks for production payments, a test key (sk_test_...) — for test payments. Each pair can have up to 4 webhooks. The optional header signs the requests so you can verify their authenticity.

Receive notifications

Tabby sends a POST request to your URL whenever the payment status changes.

Acknowledge with 200

Respond with a 200 HTTP status code to confirm the reception, and check the auth header to verify the request. Any other response (or no response) counts as a delivery error and triggers retries.

Payload

Webhooks are POST requests with a JSON body:

{
  "id": "string",
  "created_at": "2021-09-14T13:08:54Z",
  "expires_at": "2022-09-14T13:08:54Z",
  "closed_at": "2021-09-14T13:09:45Z",
  "status": "closed",
  "is_test": false,
  "is_expired": false,
  "amount": "100",
  "currency": "SAR",
  "order": {
    "reference_id": "string"
  },
  "captures": [
    {
      "id": "string",
      "amount": "100",
      "created_at": "2021-09-14T13:09:45Z",
      "reference_id": "string"
    }
  ],
  "refunds": [
    {
      "id": "string",
      "amount": "100",
      "created_at": "2021-09-14T14:14:02Z",
      "reference_id": "string",
      "reason": "string"
    }
  ],
  "meta": {
    "order_id": null,
    "customer": null
  },
  "token": "string"
}

Webhook payloads use lowercase statuses ("authorized"), while the Retrieve Request returns uppercase ("AUTHORIZED") — this is expected. See Payment Statuses.

Supported Events

The payload content depends on the event:

Event	Webhook payment status	Payload update
Authorize	authorized	”status”: “authorized”
Capture	authorized	capture info is added to captures.[] array
Close	closed	”status”: “closed” and “closed_at” updated
Reject	rejected	”status”: “rejected”
Expire (Optional)	expired	”status”: “expired”, “expired_at” and “is_expired” updated
Refund	closed	refund info is added to refunds.[] array
Update	the same as before the Update Request	order.reference_id updated

The “expire” event is optional — ask the Tabby team to enable it for your store if you want notifications when a payment is cancelled by the customer or expires.

A Typical Payment

For a regular successful order you will receive three notifications:

Payment authorized — the payload status is authorized. Check the order and process it in your OMS if it wasn’t processed yet, then send the Capture Request.
Payment captured — the payload status is still authorized, with your capture added to the captures array. No action is required.
Payment closed — the payload status is closed: the payment is completed and confirmed from both sides. No action is required.

Looking for notifications about disputes raised on your payments? See Dispute webhooks — a separate, opt-in webhook enabled by request to the Integrations Team.

Best Practices

Respond fast. Acknowledge the webhook with 200 right away and process it asynchronously, instead of holding the response until processing is done.
Expect disorder and duplicates. Webhooks are asynchronous: the delivery order is not guaranteed and the same event may occasionally arrive twice — ignore a notification you have already processed, and see Handling Edge Cases below.
Filter events. You receive notifications for all payment events — process only the ones you need.

Allowlist Tabby server IPs:

166.36.90
166.35.211
166.34.222
166.37.207
93.76.191
166.128.182
166.170.3
166.249.7

To test and debug webhooks, use a tool like Webhook.site to inspect the payload and headers Tabby sends to your endpoint.

Handling Edge Cases

These three situations occur in every production integration. Handling them wrong is the most common cause of “lost” payments and duplicate captures.

The webhook can arrive before your own order is saved

Tabby sends the authorized webhook as soon as the customer completes the payment — which can be before your checkout code has committed the order to your database. If your handler looks up the order, finds nothing, and still acknowledges with 200, that event is gone for good and the payment sits unprocessed. Do this instead: when the webhook references a payment you cannot match yet, respond with a non-200 status (e.g. 404). Tabby treats it as a delivery error and retries — by the next attempt your transaction has landed and the event processes normally. Acknowledge with 200 only when you either processed the event or deliberately chose to ignore it. It also pays to store the raw event before processing — an audit log of received webhooks makes every “where did the payment go” investigation trivial.

Statuses only move forward

A closed event can arrive before the authorized one. Treat payment status as a one-way street — authorized → closed — and never downgrade: if your record already says closed, ignore a late authorized event instead of overwriting.

A capture confirmation is not a request to capture

The second notification in A Typical Payment — authorized with your capture in the captures array — confirms your own capture. Before triggering a capture from a webhook, check that captures is empty; if it isn’t, the payment is already being settled and no action is needed.

Retry Attempts

A webhook request times out after 1 minute. If it times out or gets any response other than 200, Tabby resends it up to 4 more times with an exponential interval between attempts (1–4 minutes). Retries don’t block other notifications — Tabby keeps sending webhooks for other payment events as they occur.

Introduction

E-commerce Platforms

Online Custom Integration

Offline Integrations

Testing Guidelines

Payment webhooks

How They Work

Payload

Supported Events

A Typical Payment

Best Practices

Handling Edge Cases

The webhook can arrive before your own order is saved

Statuses only move forward

A capture confirmation is not a request to capture

Retry Attempts

​How They Work

​Payload

​Supported Events

​A Typical Payment

​Best Practices

​Handling Edge Cases

​The webhook can arrive before your own order is saved

​Statuses only move forward

​A capture confirmation is not a request to capture

​Retry Attempts

How They Work

Payload

Supported Events

A Typical Payment

Best Practices

Handling Edge Cases

The webhook can arrive before your own order is saved

Statuses only move forward

A capture confirmation is not a request to capture

Retry Attempts