Webhook destinations
Webhook destinations
Use a webhook when your own receiving system will handle a batch of decisions.
Ask its technical owner for the URL and whether it expects signed requests.
The receiving system decides what to do with the batch; Twelfth sending it
successfully does not prove the downstream action happened.
Add a destination → Webhook, with a URL and, for signed requests, a shared
secret (at least 8 characters).
Twelfth POSTs each batch of decisions as JSON:
{
"destination": { "id": "…", "name": "Supplier orders" },
"sentAt": "2026-09-28T04:10:00.000Z",
"lines": [
{
"lineId": "…",
"decisionId": "…",
"kind": "purchase_order",
"fields": { "SKU": "ABC-123", "Qty": 24, "…": "…" },
"line": { "twelfth": { "…": "…" }, "source": { "…": "…" }, "decision": { "…": "…" } }
}
]
}
Every request carries an Idempotency-Key, X-Twelfth-Destination and
X-Twelfth-Timestamp (Unix seconds). With a secret set, it also carries
X-Twelfth-Signature: sha256=HMAC_SHA256(secret, "<timestamp>.<body>")
over the raw body. Reply with a successful 2xx response when the batch has been accepted; to hand back your own reference
per line, include { "references": { "<lineId>": "PO-48812" } }. A line with a
reference is acknowledged. Anything other than a 2xx is a failed attempt and
is retried.
Receiver requirements
Your technical team should verify the signature when a secret is configured
and use Idempotency-Key to handle repeated requests once. Twelfth includes
the key; duplicate protection depends on the receiver honouring it.
A successful response without per-line references is recorded as delivered.
References acknowledge individual lines. A reference alone does not mark a
line Executed. Choose only the decision kinds this receiver understands;
Product updates requires explicit opt-in.