API
Setup & Configuration

Setup & Configuration

This page explains how to configure webhook endpoints to receive real-time event notifications from Safe Infrastructure.

Webhooks require a Growth or Scale plan. See Pricing & Plans for details.

Prerequisites

Before setting up webhooks, you need:

  1. A Safe Infrastructure account on the Growth or Scale plan.
  2. An API key from the developer dashboard ↗ (opens in a new tab).
  3. A publicly accessible HTTPS endpoint that can receive POST requests.

Configuring a webhook endpoint

Via the developer dashboard

  1. Log in to the developer dashboard (opens in a new tab).
  2. Navigate to Webhooks.
  3. Click Add Endpoint.
  4. Enter your endpoint URL (must be HTTPS).
  5. Select the event types you want to subscribe to.
  6. Optionally, filter by chain ID or Safe address.
  7. Save your configuration.

Endpoint requirements

Your webhook endpoint must:

  • Accept POST requests with Content-Type: application/json.
  • Respond with a 2xx HTTP status code within a reasonable timeout (recommended: under 5 seconds).
  • Be publicly reachable over HTTPS.

Example: Minimal webhook receiver (Node.js)


_30
import express from 'express';
_30
_30
const app = express();
_30
app.use(express.json());
_30
_30
app.post('/webhooks/safe', (req, res) => {
_30
const event = req.body;
_30
_30
console.log(`Received event: ${event.type} for Safe ${event.address}`);
_30
_30
// Process the event asynchronously
_30
processEvent(event).catch(console.error);
_30
_30
// Acknowledge receipt immediately
_30
res.status(200).send('OK');
_30
});
_30
_30
async function processEvent(event) {
_30
switch (event.type) {
_30
case 'EXECUTED_MULTISIG_TRANSACTION':
_30
// Handle executed transaction
_30
break;
_30
case 'INCOMING_ETHER':
_30
// Handle incoming ETH
_30
break;
_30
// ... handle other event types
_30
}
_30
}
_30
_30
app.listen(3000, () => console.log('Webhook receiver listening on port 3000'));

Filtering

You can filter webhook subscriptions by:

  • Chain ID: Only receive events for specific networks (for example, Ethereum mainnet, Polygon).
  • Event type: Subscribe to specific event types only.
  • Address: Filter events for specific Ethereum addresses.

Security recommendations

  • Use HTTPS: Webhook endpoints must use HTTPS to protect event payloads in transit.
  • Configure an Authorization header: Add authentication to your endpoint to verify that requests originate from Safe Infrastructure.
  • Validate payloads: Check that the event payload structure matches the expected schema before processing.

Subscription limits

The number of webhook subscriptions you can configure depends on your plan:

PlanSubscription limit
GrowthStandard
ScaleHigher (custom)

Contact support@safe.global if you need additional subscriptions beyond your plan's limit.

Next steps

OverviewOverview

Was this page helpful?