# 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

1. **Subscribe**: Configure a webhook endpoint URL in the [developer dashboard ↗](https://developer.safe.global).
2. **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.
3. **Process**: Your server processes the event and responds with a `200 OK` status to acknowledge receipt.

## Availability

<Callout type="info">
  Webhooks are a paid feature. Visit [Safe API plans ↗](https://safe.global/api) to find the right plan for your use case.
</Callout>

## 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. |
| `SAFE_CONFIG_UPDATED` | The owners, threshold, modules, guards, fallback handler, or singleton of a Safe changed. |
| `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. |

For the exact JSON structure of each event, see [Events supported ↗](https://github.com/safe-global/safe-events-service#events-supported) in the Safe Events Service repository.

## Retry semantics

If your endpoint doesn't respond with a `2xx` status code within the request timeout, Safe Infrastructure retries delivery:

- **Timeout**: 5 seconds per request.
- **Retries**: Up to 2 retries on transient network errors and `5xx` responses.
- **Back-off**: Exponential, starting at 200 ms with a 2× factor (200 ms, then 400 ms).

`4xx` responses are not retried. Return a `4xx` if you want to drop the delivery permanently, for example if the endpoint has been intentionally removed.

<Callout type="warning">
  Ensure your endpoint responds within 5 seconds and returns `200 OK`. Process events asynchronously to avoid timing out.
</Callout>

## Idempotency

Every webhook delivery carries an `X-Delivery-Id` header, a stable UUID that stays the same across retries of the same event. Use it to deduplicate events on your side:

```
X-Delivery-Id: 9f06d5ca-3b22-46b3-a85e-4fc5878126ab
```

If you receive two requests with the same `X-Delivery-Id`, treat them as the same event. This guarantees you process each event exactly once, even if the network is flaky and a delivery gets retried.

## 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: the [Safe Queue Service](./safe-queue-service-overview.mdx) for transaction proposals, confirmations, messages, and delegates, and the [Safe Transaction Service](./transaction-service-overview.mdx) for on-chain data.
- Safe Infrastructure sends notifications for blockchain reorgs. Always verify event data against the API to ensure consistency.
- `SAFE_CONFIG_UPDATED` is sent once per change, not once per transaction. For example, a `swapOwner` call sends two events, one with `REMOVED_OWNER` and one with `ADDED_OWNER`. The threshold is only reported when its value changes.
- In a `SAFE_CONFIG_UPDATED` event, `change` says what happened, and `data` holds the value that the change refers to: the owner or module that was added or removed, or the new threshold, guard, module guard, fallback handler, or singleton. `change` is one of `ADDED_OWNER`, `REMOVED_OWNER`, `CHANGED_THRESHOLD`, `ENABLED_MODULE`, `DISABLED_MODULE`, `CHANGED_GUARD`, `CHANGED_MODULE_GUARD`, `CHANGED_FALLBACK_HANDLER`, or `CHANGED_MASTER_COPY`.
- In a `SAFE_CONFIG_UPDATED` event, `status` is the configuration of the Safe right after the Safe call that made the change, not its current state. Two changes made by the same call, such as the two events of a `swapOwner`, can carry the same `status`. Events can arrive out of order, so read the current state of the Safe from the [Safe Transaction Service](./transaction-service-overview.mdx).
- Treat the payload schema as **forward-compatible**. We may add new fields to existing events at any time, so your endpoint should ignore unknown fields rather than reject them. Avoid strict validation that fails on extra properties.

## Next steps

- [Setup & Configuration](./webhooks-setup.mdx): Configure your webhook endpoints.
- [Quotas & Limits](./api-authentication.mdx): Understand how webhook deliveries affect your quota.
