Webhooks

The platform tells your systems what happened through webhooks, which are HTTP POST requests that it sends to an endpoint you register, each one signed with that endpoint's secret. Each request carries one event, such as token.transfer.final, which confirms a token transfer. The platform selects a new event for your endpoint when one of the endpoint's subscription patterns matches the event name. When a chain reorganisation replaces recent blocks, an automatic correction can also follow a provisional event your endpoint already received.

Use webhooks when a system must react to changes, such as an accounting ledger or a monitoring pipeline. Use Platform API reads when you need current state or must reconcile an uncertain notification. Registering an endpoint and receiving notifications change no asset ownership and start no transfers.

Your receiver must expect the same event more than once. The platform retries a failed attempt, and a reply that takes longer than the attempt timeout counts as a failure, even when your system already processed the request. Each repeat carries the same webhook-id. An event also reports a lifecycle state, such as provisional or final, which says how far the reported fact has progressed, and a later event can retract an earlier one. Your receiver verifies each signature, processes each event id once and acts on the lifecycle state. A retraction withdraws an earlier reported fact: reverse only effects your system applied, using the earlier event id or the payload identifiers. After 30 failed attempts in a row the platform switches the endpoint off, and while it is off the platform records no events for it. Repair the receiver before recovering deliveries. Resend adds one more attempt to a delivery, and Replay sends a stored event again as a new event. Both recover only events the platform recorded, so read what happened while the endpoint was off from the Platform API. The failure runbook covers that recovery. Attempt outcomes remain in the endpoint's delivery history.

One event reaches one endpoint in three stages:

1. Subscriptions. For an initial event, the platform compares its name with your endpoint's subscription patterns. A match queues the event for your endpoint with its own event id, evt_id. A chain reorganisation can later send a correction for a delivered provisional event without matching the correction against your subscriptions. When no pattern matches, the platform queues no initial event. Subscriptions lists the patterns and the events that the default subscriptions skip.
2. Delivery. Each attempt is a signed POST request, and every attempt for the event carries the same webhook-id header, equal to evt_id. A retryable failure gets another attempt after a backoff delay. A Resend, which you request for one delivery, adds another attempt with the same id. A Replay, which you request for one event or a block range, sends each event again as a new event with a new evt_id and sets is_replay to true. Consuming webhooks states which failures the platform retries and how Resend and Replay work.
3. Your endpoint. Verify the signature on every request with your endpoint's signing secret. Then deduplicate on evt_id: process each id once, and reply with a 2xx status to a repeat so the platform records it as delivered. Then act on the fact's lifecycle_state, not on the event-name suffix. The setup guide shows the signature check, and Lifecycle states says what each state means.

Where to find what#

Related#

• Webhook Delivery: the concept page on signed delivery, retries and the circuit breaker that pauses a failing endpoint.
• Platform Event: the concept page on how the platform names and records an event, with a figure of the lifecycle states.
• Webhook deliveries failing: the runbook for an endpoint that stopped receiving events.
• Webhook endpoints in the Console: create an endpoint, read its deliveries, and resend or replay events without the API.
• Machine-readable event definitions: an AsyncAPI document, a standard format for describing event interfaces, with the envelope and payload schema of each event.