Webhooks

Webhooks notify your server about product, customer, and order changes. Create a subscription with an HTTPS URL and the exact WebhookEventType values you need.

Create a subscription

Store the returned secret in a secret manager. Rotate it by replacing the subscription when your operational policy requires rotation.

Delivery contract

Thor sends an HTTP POST with an application/json event envelope. Important headers are:

  • Thor-Signature: t=<unix-seconds>,v1=<hex-hmac>.
  • Thor-Topic: the dot-notated event topic.
  • Thor-Project: the project identifier.
  • Thor-Webhook-Id: the subscription ID.
  • Thor-Triggered-At: an ISO 8601 timestamp.
  • Thor-Event-Id: the delivery ID.

The body contains id, object, created, idempotency_key, data, and type. Treat fields you do not recognize as forward-compatible additions.

Verify before parsing

  1. Read the raw request bytes. Do not parse and reserialize them first.
  2. Parse t and v1 from Thor-Signature.
  3. Reject timestamps outside a short tolerance appropriate for your system.
  4. Compute HMAC-SHA256 over <t>.<raw-body> using the subscription secret.
  5. Hex-encode the digest in lowercase and compare it to v1 with a constant-time comparison.
  6. Only then parse and dispatch the event.

Respond quickly and process idempotently

Return a 2xx response within 30 seconds. Queue slow work and acknowledge after the event has been durably accepted. Deduplicate with idempotency_key or Thor-Event-Id; webhook consumers must be safe to run more than once.

Non-2xx, timeout, and network responses are recorded on the delivery. Inspect deliveries through the subscription or webhookDelivery. To resend a delivery, call webhookDeliveryResend; the resend keeps the original idempotency key.