Support webhooks

Support webhooks notify your backend when merchant-visible ticket, refund, or chargeback state changes. They use the existing durable webhook delivery, signature, retry, and deduplication pipeline.

Prerequisites: configure a public HTTPS webhook URL and explicitly select the support events you need. New event selectors are opt-in and are never added to an existing subscription automatically.

Events

Event selector	Meaning
`ticket.created`	A public ticket was created
`ticket.updated`	Merchant-visible ticket data or comment content changed
`ticket.status_changed`	The public ticket status changed
`ticket.comment.created`	A merchant-visible comment was added
`ticket.reopened`	A resolved/closed ticket was reopened
`refund.requested`	A monetary refund request was durably accepted
`refund.status_changed`	The refund request status changed
`chargeback.created`	A chargeback became visible to the merchant

Configure support event selectors through Developer Center or during onboarding. Existing payment event selections and per-payment callback URLs are unchanged.

Payload

The signed wire body contains the durable event ID, occurrence time, resource type, public identifiers, and a small allowlist of state/reference timestamps:

{
  "id": "11111111-1111-4111-8111-111111111111",
  "created_at": "2026-07-15T12:00:00.000Z",
  "data": {
    "event_type": "ticket.reopened",
    "type": "ticket",
    "identifiers": {
      "c_id": "merchant-ticket-1",
      "h_id": "22222222-2222-4222-8222-222222222222"
    },
    "status": "open",
    "previous_status": "resolved",
    "payment_h_id": "33333333-3333-4333-8333-333333333333",
    "updated_at": "2026-07-15T12:00:00.000Z"
  }
}

data.event_type is the subscribed selector and data.type is ticket, refund, or chargeback. c_id is omitted for resources without a merchant identifier. Depending on the event, the safe optional fields are status, previous_status, payment_h_id, payment_c_id, reference, created_at, updated_at, resolved_at, closed_at, requested_at, and processed_at.

Webhooks intentionally omit comment bodies, descriptions, PII, staff identities, assignment/team data, internal tags, raw metadata, storage keys, and audit payloads. Query the relevant *.get or comments method after receiving a notification when you need current details.

Headers and signatures

Header	Description
`X-Webhook-Id`	Durable event/delivery identifier; matches the webhook event ID
`X-Webhook-Timestamp`	ISO 8601 delivery timestamp
`X-Webhook-Nonce`	Per-delivery nonce
`X-Webhook-Signature-V3`	Preferred `HMAC-SHA512(timestamp.nonce.webhookId.rawBody, webhook secret)`
`X-Webhook-Signature-V2`	Compatibility `SHA512(timestamp + rawBody + webhook secret)`
`X-Data-Hash`	Compatibility `SHA512(rawBody + webhook secret)`

Verify the exact raw request bytes before JSON parsing. Prefer V3, require a recent timestamp, and remember processed event IDs. The same logical event can be delivered more than once with new delivery metadata.

Verify a delivery

# Save the exact body as webhook-body.json and read headers without editing them.
EXPECTED=$(
  { printf '%s.%s.%s.' "$X_WEBHOOK_TIMESTAMP" "$X_WEBHOOK_NONCE" "$X_WEBHOOK_ID"; cat webhook-body.json; } |
    openssl dgst -sha512 -hmac 'your_webhook_secret' -r | awk '{print $1}'
)
test "$EXPECTED" = "$X_WEBHOOK_SIGNATURE_V3" || { echo 'invalid signature'; exit 1; }

import hashlib, hmac, json
from datetime import datetime, timezone

raw_body = request.get_data()
timestamp = request.headers["X-Webhook-Timestamp"]
nonce = request.headers["X-Webhook-Nonce"]
event_id = request.headers["X-Webhook-Id"]
received = request.headers["X-Webhook-Signature-V3"]
message = b".".join([timestamp.encode(), nonce.encode(), event_id.encode(), raw_body])
expected = hmac.new(b"your_webhook_secret", message, hashlib.sha512).hexdigest()
if not hmac.compare_digest(expected, received):
    return {"error": "invalid signature"}, 400
payload = json.loads(raw_body)
enqueue_once(payload["id"], payload)
return {"received": True}, 200

import crypto from "node:crypto";

function validV3(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const nonce = headers["x-webhook-nonce"];
  const eventId = headers["x-webhook-id"];
  const received = headers["x-webhook-signature-v3"] || "";
  const prefix = Buffer.from(`${timestamp}.${nonce}.${eventId}.`, "utf8");
  const expected = crypto
    .createHmac("sha512", secret)
    .update(Buffer.concat([prefix, rawBody]))
    .digest("hex");
  return (
    /^[a-f0-9]{128}$/i.test(received) &&
    crypto.timingSafeEqual(
      Buffer.from(expected, "hex"),
      Buffer.from(received, "hex"),
    )
  );
}

// Use express.raw({ type: "application/json" }), validate timestamp skew,
// then JSON.parse(req.body) only after validV3(req.body, req.headers, secret).

Also reject missing replay headers and timestamps outside your accepted window (five minutes is recommended). Rotate an exposed webhook secret immediately; API-key rotation does not change callback verification.

Delivery and idempotency

The resource owner commits the merchant-visible change and an outbox event atomically. Gateway then persists one webhook delivery per selected subscription and uses the durable event ID for deduplication. Temporary NATS, process, or HTTP failures are retried; repeated infrastructure failures are retained for operational recovery. Merchant endpoints must still assume at-least-once, potentially out-of-order delivery:

Verify V3 and timestamp before parsing.
Insert payload.id into a table with a unique constraint.
Return HTTP 2xx quickly after durable local enqueue.
Fetch current state by data.identifiers.h_id when processing asynchronously.
Ignore older state notifications when your stored resource version/timestamp is newer.

Do not use request_id as webhook dedupe state; use the top-level event id.

Retry behavior

Any HTTP 2xx response completes an attempt. Network errors, timeouts, URL safety failures, circuit-breaker blocks, and non-2xx responses are failures. Retries use exponential backoff with jitter, so delivery order is not guaranteed.

Error handling

Symptom	Recovery
Signature mismatch	Verify raw bytes, webhook secret, header casing, and V3 concatenation order
Duplicate `id`	Return 2xx without replaying the business side effect
Unknown resource locally	Query the corresponding public `*.get` method; creation webhook can arrive before another local projection
Missing optional field	Fetch current state; event payloads are intentionally minimal
Repeated delivery	Check that your endpoint returns 2xx within its timeout and does not perform slow work inline

Best practices

Use a dedicated HTTPS route with raw-body capture and strict body limits.
Store the event id, resource public IDs, and received timestamp before acknowledging.
Keep one handler per event selector even if several selectors share a URL.
Never log signatures, raw comment content, presigned URLs, API secrets, or webhook secrets.

Getting Started

Guides

SDKs & Examples

Reference

Support webhooks

Support webhooks

Events

Payload

Headers and signatures

Verify a delivery

Delivery and idempotency

Retry behavior

Error handling

Best practices

​Support webhooks

​Events

​Payload

​Headers and signatures

​Verify a delivery

​Delivery and idempotency

​Retry behavior

​Error handling

​Best practices

Support webhooks

Events

Payload

Headers and signatures

Verify a delivery

Delivery and idempotency

Retry behavior

Error handling

Best practices