Webhooks Overview
Webhooks allow you to receive real-time HTTP notifications when events occur on Safe Smart Accounts. Instead of polling the API for changes, your application receives push notifications as events happen, enabling efficient, event-driven architectures.
How webhooks work
- Subscribe: Configure a webhook endpoint URL in the developer dashboard ↗ (opens in a new tab).
- Receive: When a relevant event occurs (for example, a transaction is proposed, confirmed, or executed), Safe Infrastructure sends an HTTP POST request to your endpoint with event details in the JSON body.
- Process: Your server processes the event and responds with a
200 OKstatus to acknowledge receipt.
Availability
Webhooks are a paid feature. Visit Safe API plans ↗ (opens in a new tab) to find the right plan for your use case.
Webhook deliveries do not count as API units
Webhook deliveries are not counted toward your monthly API unit quota. Only HTTP requests you make to the API consume API units.
1 API unit = 1 HTTP request. Webhook deliveries are excluded.
Consider using webhooks to reduce your API usage if you're currently polling for updates.
Supported event types
| Event type | Description |
|---|---|
NEW_CONFIRMATION | A new signature was added to a pending transaction. |
EXECUTED_MULTISIG_TRANSACTION | A multisig transaction was executed on-chain. |
PENDING_MULTISIG_TRANSACTION | A new multisig transaction was proposed. |
DELETED_MULTISIG_TRANSACTION | A pending multisig transaction was deleted. |
INCOMING_TOKEN | An ERC-20 token transfer was received. |
INCOMING_ETHER | A native token (ETH) transfer was received. |
OUTGOING_TOKEN | An ERC-20 token transfer was sent. |
OUTGOING_ETHER | A native token (ETH) transfer was sent. |
MODULE_TRANSACTION | A transaction was executed via a module. |
MESSAGE_CREATED | A new off-chain message was created. |
MESSAGE_CONFIRMATION | A confirmation was added to an off-chain message. |
SAFE_CREATED | A new Safe was created. |
REORG_DETECTED | A blockchain reorganization was detected. |
NEW_DELEGATE | A new delegate was added. |
UPDATED_DELEGATE | An existing delegate was updated. |
DELETED_DELEGATE | A delegate was removed. |
Retry semantics
If your endpoint does not respond with a 2xx status code, Safe Infrastructure retries the delivery:
- Retries use exponential back-off.
- Deliveries are retried a limited number of times before being marked as failed.
Ensure your webhook endpoint responds quickly (within a few seconds) and returns 200 OK to acknowledge receipt. Process events asynchronously to avoid timeouts.
Security
We recommend configuring an Authorization header on your webhook endpoint so that only authenticated requests from Safe Infrastructure are accepted. You can set this up in the developer dashboard when creating your webhook. This prevents malicious actors from posting fake events to your service.
Important notes
- Webhook payloads are intentionally minimal. They serve as signals to notify your application that something changed. Use the API to fetch full details after receiving an event.
- Safe Infrastructure sends notifications for blockchain reorgs. Always verify event data against the API to ensure consistency.
Next steps
- Setup & Configuration: Configure your webhook endpoints.
- Quotas & Limits: Understand how webhook deliveries affect your quota.