Skip to main content
Webhooks tell your server when an action changes state, an owner policy is confirmed, paused, resumed, or revoked, a child mandate is created or changes status, or an EIP-7702 setup progresses. You can also opt in to provisional inclusion notifications. Delivery is at least once and may be out of order. Deduplicate by event ID and treat polling as the source of truth.

Create an endpoint

In the console, open Webhooks and choose Add endpoint, or call the API:
The new webhook endpoint form with a URL, description, and event types
The URL must be https and resolve to a public address. Redirects are not followed. A project environment can have up to 10 endpoints. Send a test event with Test in the console or sendWebhookTest. If you omit eventTypes, the endpoint receives the existing selected-head and test events, but no provisional inclusion events. To receive inclusion changes, select the Provisional inclusion events choices when creating an endpoint in console 0.3.0, or create an endpoint with the relevant *.inclusion_updated types in its explicit API list. The API has no endpoint event-type update route; create a new endpoint when changing subscriptions. Published SDK 0.7.1 types API 0.7.0’s inclusion event names for createWebhookEndpoint, as shown above. The public API can create the same subscription without the SDK:
The response includes a one-time signing secret. Capture and store it server-side.
A webhook endpoint with Test, Rotate, and Disable buttons and a successful test delivery

Recent deliveries shows each attempt with its status and response code.

Events

The four *.inclusion_updated types are opt-in and carry provisional: true, the public resource IDs, workflow, transactionHash, chainId, state, previousState, sequence, outcome, block details, and observedAt. state can be included, reverted, mismatch, or orphaned. A later observation can retract an earlier included, including after the same transaction moves to a different block. pending and chain finality are not inclusion events. For inclusion events, deduplicate retries by envelope id. Track the highest sequence for each transaction hash and ignore older transitions. A delayed inclusion delivery can arrive after a selected-head event, so never let it downgrade a confirmed result. Selected-head events and the polled resource remain authoritative for confirmation, settlement, and ledger effects. The inbound Alchemy notification only triggers GOL’s own receipt check; an outbound inclusion event does not grant authority or move funds.

Verify every delivery

Each request carries gol-webhook-id, gol-webhook-timestamp, and gol-webhook-signature. The signature is v1= followed by the hex HMAC-SHA256 of timestamp.rawBody, keyed by the endpoint secret. Verify against the raw body before parsing:
Timestamps more than 5 minutes from your clock are rejected. When you rotate a secret, both secrets sign deliveries for 24 hours; pass both to verifyWebhook during the switch. See webhooks in the SDK for the endpoint management methods and a rotation example.

Retries

Respond with any 2xx within 10 seconds. Otherwise GOL retries after about 30 seconds, 2, 10, and 30 minutes, 1, 3, 6, and 12 hours, then gives up. Every attempt appears under Recent deliveries in the console and in listWebhookDeliveries. A disabled endpoint keeps pending deliveries for 72 hours.