Webhooks
What the Tanqory spec declares about webhooks today — and what it does not.
Outbound webhook events are not yet declared in the OpenAPI spec.
spec.webhooks is empty on both admin-api and ai-api, and no
endpoint declares an x-tanqory-event extension. This page documents
only what is verifiable. Subscription flow, signing, and retry policy
live in the gateway implementation; they will be added to the spec
before launch ([FOUNDER TO CONFIRM] for the target timeline + event
catalogue).
The state of the spec
We searched both Admin and AI OpenAPI documents for webhook indicators. Findings:
| Field searched | Admin API | AI API | Note |
|---|---|---|---|
spec.webhooks events | 0 | 0 | No event catalogue declared. |
Tag named Webhooks* (outbound) | 0 | 0 | No outbound webhook subscription endpoints. |
Tag named PayPal Webhooks (inbound) | 1 op | — | Tanqory receives PayPal webhooks; see the inbound webhooks note below. |
The runtime gateway does emit webhook events to subscriber URLs — the spec is simply behind the runtime. Once the spec adds an event catalogue, this page will be rewritten to enumerate every event, its payload schema, and verification headers.
The single declared webhook endpoint
There is exactly one endpoint in the spec that carries the "webhook" tag, and it is inbound, not outbound:
| Endpoint | Direction | Purpose (verbatim from spec) |
|---|---|---|
POST /api/webhooks/paypal | Inbound — Tanqory receives from PayPal | "Handle PayPal webhook events" |
This is the endpoint Tanqory exposes for PayPal's webhook deliveries to call. It is not a subscription endpoint for app developers and should not be called by integrators.
What is not yet documented (deliberate gaps)
| Gap | Status |
|---|---|
Outbound event names (e.g. order.created, store.updated) | Not declared in spec. |
| Subscription / un-subscription endpoints | Not declared in spec. |
| Payload schema per event | Not declared in spec. |
| Signature header name + algorithm | Not declared in spec. Treat the gateway implementation as authoritative until the spec is amended. |
| Retry policy + backoff schedule | Not declared in spec. |
| Delivery ordering guarantees | Not declared in spec. |
| Dead-letter handling | Not declared in spec. |
Do not infer any of the above from prior versions of this page or from code samples elsewhere. The OpenAPI spec is the truth.
Runtime patterns (provisional)
The platform team is preparing the spec amendment. Until it lands, the following are provisional and will appear on this page as verifiable contracts once declared:
- HMAC signature over
${timestamp}.${rawBody}in anX-Tanqory-Signatureheader —[FOUNDER TO CONFIRM]final header name + algorithm. - Exponential-backoff retry for non-2xx deliveries —
[FOUNDER TO CONFIRM]exact schedule + ceiling. - Per-event subscription via dashboard or API —
[FOUNDER TO CONFIRM]exact endpoint paths.
When the spec adds these, this section will become a real contract with examples and code samples. Do not build production webhook handlers against this section as written today.
Next steps
| Topic | When to read it |
|---|---|
| Errors | If your subscriber endpoint returns 5xx, deliveries will retry. |
| Rate limits | Webhook delivery volume is governed by your plan tier. |
| Status | If you stop receiving deliveries, check incident state first. |
| Trust Center | Subprocessor list — webhook delivery is in scope of data-flow disclosures. |