Receive Webhook Events
Build an endpoint that receives Agiled webhook deliveries.
Use this guide when an external system needs to receive Agiled events.
Build the receiver before enabling production webhook subscriptions. A receiver should verify authenticity, handle retries, and avoid processing the same event twice.
Build the Receiver
- Create an HTTPS endpoint that accepts
POSTrequests. - Read the raw JSON body.
- Verify the Agiled signature.
- Parse the JSON payload.
- Process the event idempotently.
- Return a
2xxresponse after the event is accepted.
Store the delivery ID or event ID before processing side effects. This lets your receiver safely ignore duplicate deliveries and retry internal work without asking Agiled to resend.
Delivery Attempts
Agiled attempts webhook delivery up to 5 times. Retry timing uses backoff windows of 60, 300, 900, 1800, and 3600 seconds.
Return 2xx only after your system has accepted the event. If processing is
slow, store the event and process it asynchronously so Agiled does not retry a
valid delivery.
Do not perform slow API calls, file processing, or customer notifications before acknowledging the delivery unless they reliably finish within your endpoint timeout. Queue the work after signature verification.
Endpoint Rules
Webhook targets must be public HTTPS endpoints that Agiled can reach. Agiled blocks private, local, and unsafe target hosts.
Troubleshooting
Use Settings > API > Deliveries to review event type, target URL, attempt count, status, and error message.
When debugging, compare the delivery ID and event type in Agiled with your receiver logs. Fix signature, timeout, DNS, TLS, and response-code issues before resending or waiting for the next event.
Test your receiver with a low-risk webhook subscription before subscribing to high-volume events. Confirm logs include enough context to find the matching Agiled delivery later.
Receiver Processing Pattern
A reliable receiver usually has two steps: accept the webhook quickly, then
process the event from an internal queue or job. The acceptance step verifies
the signature, stores the event, records idempotency, and returns 2xx.
The background step can safely call external APIs, update records, send notifications, or retry failed downstream work without causing Agiled to resend a valid delivery.
Idempotent Side Effects
Every side effect should be safe to run once even if the delivery arrives more than once. Store the event ID before processing and check it before creating external records, sending notifications, or updating another system.
If a downstream step fails after the webhook is accepted, retry from your own queue using the stored event rather than asking Agiled to redeliver manually.