Skip to main content
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

1

Register an endpoint

Register a webhook for each merchant_code + secret key pair. 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. An optional auth header can sign the requests so you can verify their authenticity.
2

Receive notifications

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

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:
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: 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:
  1. 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.
  2. Payment captured — the payload status is still authorized, with your capture added to the captures array. No action is required.
  3. 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

Webhooks are asynchronous: the delivery order is not guaranteed, and the same event may occasionally be delivered twice.
  • Respond fast. Acknowledge the webhook with 200 right away and process it asynchronously, instead of holding the response until processing is done.
  • Handle out-of-order delivery. A capture event may arrive before an authorization event — use a finite state machine or similar logic instead of assuming the order.
  • Deduplicate. Ignore a webhook if the same notification was already processed.
  • Filter events. You receive notifications for all payment events — process only the ones you need.
  • Allowlist Tabby server IPs:
To test and debug webhooks, use a tool like Webhook.site to inspect the payload and headers Tabby sends to your endpoint.

​
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.