Skip to main content
Webhooks configuration under Integrations

Settings > Integrations & API

Webhooks table with event, URL, status, created date, and the row actions menu open

Settings > Integrations & API > Webhooks

Webhooks notify your system when an order changes in TWICE Commerce. When an event fires, TWICE sends an HTTP POST to a URL you register, so you can react without polling the API.

Event types

TWICE emits three order events: The payload’s data carries the affected Order. More resources and events may be added over time.

What triggers order.updated

order.updated fires when the order itself changes and when any of its child data changes:
  • Line items
  • Stock items
  • Customers
  • Comments
  • Tags
  • Documents
  • Discounts
  • Attributes
  • Checkout fields
Payment records are not in this set — a payment write does not itself trigger order.updated. A single operation that touches multiple child rows (for example, a bulk edit that updates the order and several line items in one transaction) produces one delivery, not many. TWICE deduplicates burst changes per order so your endpoint receives a single consolidated event.
Suppression of pending orders (checkout drafts still in progress) applies to creation only: inserting a pending order emits nothing, and order.created fires when the order leaves pending status. Updates to a pending order still emit order.updated, and deleting one emits order.deleted.

How it works

Each delivery is an HTTP POST whose JSON body is an envelope describing the event. The affected resource travels in data:
string
Unique identifier of the event. Also sent in the X-Twice-Event-Id header. Deduplicate on this value.
string
The event that fired, for example order.created. One webhook receives one event type.
string
ISO 8601 timestamp of when the event occurred.
string
The resource the event concerns, for example order.
string
Identifier of the affected resource.
string
API version the payload is rendered in.
object | null
The resource in the same shape the REST API returns it. null for order.deleted.
For the Order schema carried in data, see the API reference.

API version pinning

Each webhook is pinned to the API version that was the latest when you created it, and that version is reported in apiVersion. A new API version never changes the payload shape you already receive — moving a webhook to a newer version is an explicit update.

Managing webhooks

Manage webhooks under Settings → Integrations & API → Webhooks. Create one by choosing an event type, then entering the endpoint URL that receives the POST. Target URLs must be HTTPS. The table lists each webhook with: Row actions cover the rest: View deliveries, Enable / Disable, View signing secret, and Delete. A single event can be delivered to several webhooks — for example one order.created webhook to your CRM and another to your accounting system.
Webhooks require a plan that includes them — accounts without it see an upgrade prompt under Integrations. See plans.

Delivery and retries

TWICE delivers webhooks asynchronously through a Cloud Tasks queue. A delivery succeeds on any 2xx response; any other status — or a timeout — counts as a failed attempt. A failed delivery is retried up to 3 times (4 attempts in total), roughly 10 s, 20 s and 40 s after the preceding attempt, and retrying stops 10 minutes after the first attempt. After 3 consecutive events exhaust all their attempts, the webhook is disabled automatically with the reason TOO_MANY_FAILED_DELIVERY_ATTEMPTS, and you re-enable it manually once your endpoint is reachable. Re-enabling — or repointing the webhook at another URL — starts a fresh failure window. Respond 2xx quickly. If processing is slow, acknowledge first and queue the work.

Delivery log

Every dispatched delivery is recorded. Open View deliveries on a webhook to see them at /settings/connect/integrations/webhooks/{webhookId}, filterable and sortable by result, event, event ID, trigger time, attempt count and last response.
Delivery log with the delivery detail drawer open showing the attempt timeline and payload

Delivery detail — attempt timeline and the signed envelope payload

A delivery carries one of four statuses: Open a row for the delivery detail: the event ID, trigger time, attempt count and last response, an attempt timeline with the outcome of each attempt, and the exact payload that was sent. From there you can Copy payload, or Redeliver to send the same recorded payload to the target URL again.
Deliveries recorded before the delivery log stored payloads show no payload and cannot be redelivered.
There is no test delivery. To try an endpoint before pointing production traffic at it, create a webhook against a temporary URL (the create dialog suggests webhook.site) and trigger the event.

Deduplication

The same event can arrive more than once, so your endpoint must be idempotent. Deduplicate on eventId — sent both in the body and in the X-Twice-Event-Id header. Ordering is not guaranteed either. When order matters, compare eventTime or re-fetch the current state of the resource through the API.

Verifying signatures

Every webhook has a signing secret, prefixed whsec_. TWICE signs each delivery with it and sends the signature in the X-Twice-Signature header, formatted sha256=<hex> — an HMAC-SHA256 of the exact raw request body. Verify against the raw body bytes, and parse the JSON only after the signature checks out:

Managing the secret

Open View signing secret on a webhook to reveal, copy or rotate it.
Rotating replaces the secret immediately — deliveries are signed with the new secret from that point on, so update your endpoint at the same time.
Webhooks created before signing existed have no secret and their deliveries stay unsigned until you generate one. The dialog offers Generate secret for those.

Developer Reference

Webhooks are managed via the hooks endpoints.

API: Webhooks

Open the endpoint in the API reference.

Integrations

Webhooks alongside API keys.

API Keys

Authenticate against the API.

Activity Logs

Audit trail you can reconcile against.

Order Lifecycle

When order events fire.