Resources · Integration patterns
REST APIs and webhook orchestration
Systems announce changes with signed webhooks and an orchestrator calls APIs idempotently.
Integration status: Documented pattern
A documented pattern. This product runs no webhook integrations with external systems.
Description
The source sends a signed webhook on an event; the orchestrator verifies the signature, records the event and calls the target APIs with an idempotency key and retries with backoff.
Prerequisites
- A signing secret on both sides.
- Idempotent operations or keys.
- A table of processed events.
When to use it
- Systems have stable APIs and support webhooks.
- Volumes are moderate.
- A quick reaction to events is needed.
When not to use it
- Very high volumes or ordering needs — use events.
- The source does not support signatures.
- Full synchronisation of large data sets is needed.
Reference diagram
An illustration of the components and the flow — not a running system.
01Source
- Event
- Signed webhook
02Orchestrator
- Signature check
- Record and de-duplicate
- Retries
03Targets
- REST APIs
- Dead-letter queue
The diagram as a list
| Stage | Components |
|---|---|
| Source | Event, Signed webhook |
| Orchestrator | Signature check, Record and de-duplicate, Retries |
| Targets | REST APIs, Dead-letter queue |
Security controls
- HMAC signature and timestamp verification.
- HTTPS only and an allow-list of addresses.
- Least-privilege keys for the target APIs.
Observability
- Event count and processing delay.
- Failure rate and dead-letter queue.
- Tracing with the event id.
Failure modes
| Failure | Mitigation |
|---|---|
| Webhook delivered twice | De-duplication by event id. |
| Target API not responding | Retries with backoff and a dead-letter queue. |
| Forged request | Refused on an invalid signature. |