Webhooks#

Webhooks let you receive real-time HTTP notifications when events occur in the Afosto platform — without polling the API.

How it works#

When an event fires, Afosto sends an HTTP POST request to your registered endpoint with a signed JSON payload. Your endpoint must respond with a 2xx status to acknowledge receipt.

Your system

Afosto platform

⚡ Event occurs

POST signed payload to your endpoint

X-Afosto-Hmac-Sha256 · Content-Type: application/json

Verify signature & process event

Respond 200 OK

ℹ

Tip:Respond 200 OK immediately and process the payload in a background job. Slow handlers increase the chance of retries.

Payload structure#

Every webhook delivery shares the same envelope:

Name	Type	Required	Description
`event`	String!	Required	The event name — e.g. `ORDER_OPENED`, `DELIVERED`. See [Events](/docs/webhooks/events) for the full list.
`data`	Object	Required	The event-specific payload — the full entity object at the time of the event. Shape varies per event type.
`entity_id`	String!	Required	The ID of the entity that triggered this event
`entity_type`	String!	Required	The type of entity — e.g. `order`, `delivery`
`message_id`	String!	Required	Unique delivery ID. Use this for idempotency — the same event may be delivered more than once.
`triggered_at`	Int64	Required	Unix timestamp in milliseconds when the event was triggered

{
  "event": "ORDER_OPENED",
  "data": { "id": "ord_72fca344-2a6f-4b3e-9c1d-5f8a2e7b0d93", "number": 1042, "progress": "OPEN" },
  "entity_id": "ord_72fca344-2a6f-4b3e-9c1d-5f8a2e7b0d93",
  "entity_type": "order",
  "message_id": "msg_3a1b2c4d-5e6f-7890-abcd-ef1234567890",
  "triggered_at": 1714000000000
}

Note:Always use message_id for deduplication. Network retries can result in the same event being delivered more than once.

Request headers#

Every webhook request includes these HTTP headers:

Name	Type	Required	Description
`Content-Type`	String	Required	Always `application/json`
`User-Agent`	String	Required	`Afosto/1.0 (+https://afosto.com/docs/webhooks)`
`X-Afosto-Hmac-Sha256`	String	Required	HMAC-SHA256 hex digest of the raw request body, signed with your endpoint secret. See [Signature Verification](/docs/webhooks/signature-verification).
`X-Afosto-Endpoint`	String	Required	UUID of the registered endpoint that received this delivery
`X-Afosto-Tenant`	String	Required	Your tenant identifier

Retries#

If your endpoint returns a non-2xx response (or times out), Afosto retries the delivery for up to 24 hours with an increasing backoff interval between attempts.

Afosto continuously monitors endpoint health. Endpoints that repeatedly fail are automatically disabled and stop receiving deliveries. Fix the underlying issue and re-enable the endpoint in your settings to resume delivery.

Webhooks#

How it works#

Payload structure#

Request headers#

Retries#

Endpoint health#