Webhooks

The platform tells your systems what happened through webhooks: 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. Automatic reorg corrections 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 do not themselves change asset ownership or start transfers. Your receiver controls its downstream actions.

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, 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. Persistent delivery failures can disable an endpoint. Repair the receiver before recovering deliveries with Resend or Replay; 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 reorg 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; do not infer it from the event-name suffix. The setup guide shows the signature check, and Lifecycle states says what each state means.

Where to find whatCopy Anchor Link

RelatedCopy Anchor Link

• 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.
• Machine-readable event definitions: an AsyncAPI document, a standard format for describing event interfaces, with the envelope and payload schema of each event.