Overview
Notifuse handles two types of webhooks:
-
Incoming webhooks - Callbacks from email providers (Amazon SES, Mailgun, Postmark, etc.) that notify Notifuse about email events like bounces, complaints, and deliveries. These are configured automatically when you set up an email integration.
-
Outgoing webhooks - HTTP callbacks that Notifuse sends to your server when events occur. This is what this feature page covers.
Outgoing webhooks allow you to receive HTTP POST requests to your server when specific events occur in Notifuse. This enables you to:
- Sync contact data to your CRM or other systems
- Trigger workflows in external automation tools
- Build custom integrations and dashboards
- React to email engagement events in real-time
Creating a Webhook Subscription
Create a webhook subscription in the console, from Settings → Webhooks → Add endpoint, where you choose the URL and the event types:
Or create it through the API:
curl -X POST "https://your-instance.com/api/webhookSubscriptions.create" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "your_workspace",
"name": "Production Webhook",
"url": "https://api.example.com/webhooks/notifuse",
"event_types": ["contact.created", "contact.updated", "email.sent"]
}'
Available Event Types
Contact Events
| Event | Description |
|---|---|
contact.created | A new contact was added to the workspace |
contact.updated | Contact data was modified |
contact.deleted | A contact was permanently deleted |
List Events
| Event | Description |
|---|---|
list.subscribed | Contact subscribed to a list |
list.unsubscribed | Contact unsubscribed from a list |
list.confirmed | Contact confirmed double opt-in subscription |
list.resubscribed | Previously unsubscribed contact resubscribed |
list.bounced | Email to contact bounced |
list.complained | Contact marked email as spam |
list.pending | Contact subscription is awaiting confirmation |
list.removed | Contact was removed from list |
Segment Events
| Event | Description |
|---|---|
segment.joined | Contact entered a segment (matched segment criteria) |
segment.left | Contact left a segment (no longer matches criteria) |
Email Events
| Event | Description |
|---|---|
email.sent | Email was sent to contact |
email.delivered | Email delivery was confirmed by the recipient’s server |
email.opened | Contact opened the email |
email.clicked | Contact clicked a link in the email |
email.bounced | Email delivery failed |
email.complained | Contact marked email as spam |
email.unsubscribed | Contact unsubscribed via email link |
Custom Events
| Event | Description |
|---|---|
custom_event.created | A new custom event was recorded |
custom_event.updated | A custom event was updated |
custom_event.deleted | A custom event was soft-deleted |
Custom Event Filters
For custom events, you can optionally filter by goal_types and event_names:
{
"event_types": ["custom_event.created"],
"custom_event_filters": {
"goal_types": ["purchase", "subscription"],
"event_names": ["orders/fulfilled", "payment.succeeded"]
}
}
Filtering by List and Segment
By default a subscription to list.* events receives an event for every list in the workspace, and a subscription to segment.* events one for every segment. Narrow that with list_ids and segment_ids:
{
"event_types": ["list.subscribed", "list.unsubscribed", "segment.joined"],
"list_ids": ["newsletter", "product_updates"],
"segment_ids": ["vip_customers"]
}
list_idsapplies to thelist.*events only,segment_idsto thesegment.*events only. Neither affects contact, email or custom event types.- Omitting a filter, or sending an empty array, means “every list” or “every segment” — which is how every subscription created before these filters existed keeps behaving.
- Both filters can be changed later with
webhookSubscriptions.update.
Filter whenever you can. A workspace with large lists generates one delivery per contact per list event, so a subscription that only cares about one list but subscribes to all of them does real work on your instance for events it will discard.
Subscription Fields
Alongside its name, URL and event types, a subscription reports:
| Field | Description |
|---|---|
enabled | Whether the subscription is currently delivering |
source | What created it. Absent for a subscription you created yourself; zapier for one created by the Zapier integration |
consecutive_failures | Delivery attempts that have failed back to back. Reset to zero by the first success |
failing_since | When the current run of failures started. Cleared by the first success |
disabled_reason | Why the subscription was switched off automatically. Absent for one you switched off yourself |
last_delivery_at | When a delivery last succeeded |
A subscription carrying a source was created by another tool and is owned by it. Deleting a Zapier-created subscription from Notifuse silently breaks the Zap behind it, and the Zap will not recreate it on its own. Turn the Zap off in Zapier instead.
When Notifuse Switches a Subscription Off
An endpoint that stops answering is retired automatically, but only once it has been failing persistently. Both conditions have to be met: 20 consecutive failures, and a run of them that has been going for more than two hours. A short outage — a deploy, a restart, a receiver that is briefly unreachable during an import — never switches your subscription off, however many deliveries it refuses in the meantime. Those deliveries are retried on the usual backoff.
An endpoint answering 410 Gone is the exception and is retired at once, because that status means the receiver is telling you the subscription no longer exists.
Switching a subscription back on clears its failure history, so it starts from a clean slate rather than being retired again on the next hiccup.
Where Notifuse Can Deliver
Your endpoint has to be reachable from the public internet. Notifuse refuses to connect to private, loopback, link-local and reserved addresses — including the cloud instance metadata endpoint — and checks this again on every redirect, so a public URL that redirects to an internal one is refused as well. A subscription whose URL names such an address is rejected when you save it.
Self-hosted only: if you run Notifuse yourself and deliberately deliver webhooks to a service on your own private network — a container on the same Docker network, an internal automation tool — set WEBHOOK_DELIVERY_ALLOW_PRIVATE_HOSTS=true. Leave it unset on any deployment where someone you would not trust with your internal network can create subscriptions or edit automations. The same setting covers automation webhook nodes.
A delivery refused this way is retried like any other failure, but it never counts toward switching the subscription off, so correcting the URL or the setting is enough to get it delivering again.
Payload Structure
All webhook payloads follow this structure:
{
"id": "delivery_abc123",
"type": "contact.created",
"timestamp": "2024-01-15T10:30:00Z",
"workspace_id": "ws_1234567890",
"data": {
// Event-specific data
}
}
| Field | Description |
|---|---|
id | Unique identifier for the webhook delivery |
type | The event type that triggered the webhook |
timestamp | ISO 8601 timestamp when the webhook was sent |
workspace_id | The workspace where the event occurred |
data | Event-specific payload data |
Example: Contact Created
{
"id": "delivery_abc123",
"type": "contact.created",
"timestamp": "2024-01-15T10:30:00Z",
"workspace_id": "ws_1234567890",
"data": {
"email": "user@example.com",
"id": "contact_12345",
"external_id": "ext_67890",
"first_name": "John",
"last_name": "Doe",
"tags": ["newsletter", "customer"],
"tracking_opens_consent": "granted",
"tracking_clicks_consent": null,
"tracking_consent_updated_at": "2024-01-15T10:30:00Z",
"tracking_consent_source": "api",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
Example: Email Sent
{
"id": "delivery_def456",
"type": "email.sent",
"timestamp": "2024-01-15T10:30:00Z",
"workspace_id": "ws_1234567890",
"data": {
"message_id": "msg_xyz789",
"email": "user@example.com",
"subject": "Welcome to our newsletter",
"broadcast_id": "bc_abc123",
"template_id": "welcome_email",
"created_at": "2024-01-15T10:30:00Z"
}
}
Example: Email Opened
{
"id": "delivery_ghi789",
"type": "email.opened",
"timestamp": "2024-01-15T11:45:00Z",
"workspace_id": "ws_1234567890",
"data": {
"message_id": "msg_xyz789",
"email": "user@example.com",
"subject": "Welcome to our newsletter",
"broadcast_id": "bc_abc123",
"template_id": "welcome_email",
"created_at": "2024-01-15T11:45:00Z"
}
}
Example: Segment Joined
{
"id": "delivery_jkl012",
"type": "segment.joined",
"timestamp": "2024-01-15T10:30:00Z",
"workspace_id": "ws_1234567890",
"data": {
"email": "user@example.com",
"contact_id": "contact_12345",
"segment_id": "seg_vip_customers",
"segment_name": "VIP Customers",
"created_at": "2024-01-15T10:30:00Z"
}
}
Verifying Webhook Signatures
Notifuse signs all webhook payloads using the Standard Webhooks specification with HMAC-SHA256.
Headers
Each webhook request includes these headers:
| Header | Description |
|---|---|
webhook-id | Unique identifier for the webhook delivery |
webhook-timestamp | Unix timestamp when the webhook was sent |
webhook-signature | HMAC-SHA256 signature of the payload |
Verifying the Signature
- Extract the timestamp and signature from the headers
- Construct the signed payload:
{webhook-id}.{webhook-timestamp}.{body} - Compute HMAC-SHA256 using your webhook secret
- Compare with the provided signature
Code Examples
const crypto = require('crypto');
function verifyWebhook(payload, headers, secret) {
const msgId = headers['webhook-id'];
const msgTimestamp = headers['webhook-timestamp'];
const msgSignature = headers['webhook-signature'];
// Check timestamp is within 5 minutes
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - parseInt(msgTimestamp)) > 300) {
throw new Error('Timestamp too old');
}
// Construct signed payload
const signedPayload = `${msgId}.${msgTimestamp}.${payload}`;
// Compute signature
const secretBytes = Buffer.from(secret.replace('whsec_', ''), 'base64');
const expectedSignature = crypto
.createHmac('sha256', secretBytes)
.update(signedPayload)
.digest('base64');
// Extract v1 signature
const signatures = msgSignature.split(' ');
for (const sig of signatures) {
const [version, signature] = sig.split(',');
if (version === 'v1' && signature === expectedSignature) {
return true;
}
}
throw new Error('Invalid signature');
}import hmac
import hashlib
import base64
import time
def verify_webhook(payload: str, headers: dict, secret: str) -> bool:
msg_id = headers.get('webhook-id')
msg_timestamp = headers.get('webhook-timestamp')
msg_signature = headers.get('webhook-signature')
# Check timestamp is within 5 minutes
now = int(time.time())
if abs(now - int(msg_timestamp)) > 300:
raise ValueError('Timestamp too old')
# Construct signed payload
signed_payload = f"{msg_id}.{msg_timestamp}.{payload}"
# Compute signature
secret_bytes = base64.b64decode(secret.replace('whsec_', ''))
expected_signature = base64.b64encode(
hmac.new(secret_bytes, signed_payload.encode(), hashlib.sha256).digest()
).decode()
# Extract v1 signature
for sig in msg_signature.split(' '):
version, signature = sig.split(',')
if version == 'v1' and signature == expected_signature:
return True
raise ValueError('Invalid signature')package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
"errors"
"fmt"
"math"
"strconv"
"strings"
"time"
)
func VerifyWebhook(payload string, headers map[string]string, secret string) error {
msgID := headers["webhook-id"]
msgTimestamp := headers["webhook-timestamp"]
msgSignature := headers["webhook-signature"]
// Check timestamp is within 5 minutes
ts, _ := strconv.ParseInt(msgTimestamp, 10, 64)
now := time.Now().Unix()
if math.Abs(float64(now-ts)) > 300 {
return errors.New("timestamp too old")
}
// Construct signed payload
signedPayload := fmt.Sprintf("%s.%s.%s", msgID, msgTimestamp, payload)
// Compute signature
secretBytes, _ := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
h := hmac.New(sha256.New, secretBytes)
h.Write([]byte(signedPayload))
expectedSig := base64.StdEncoding.EncodeToString(h.Sum(nil))
// Extract v1 signature
for _, sig := range strings.Split(msgSignature, " ") {
parts := strings.SplitN(sig, ",", 2)
if len(parts) == 2 && parts[0] == "v1" && parts[1] == expectedSig {
return nil
}
}
return errors.New("invalid signature")
}<?php
function verifyWebhook(string $payload, array $headers, string $secret): bool {
$msgId = $headers['webhook-id'] ?? '';
$msgTimestamp = $headers['webhook-timestamp'] ?? '';
$msgSignature = $headers['webhook-signature'] ?? '';
// Check timestamp is within 5 minutes
$now = time();
if (abs($now - (int)$msgTimestamp) > 300) {
throw new Exception('Timestamp too old');
}
// Construct signed payload
$signedPayload = "{$msgId}.{$msgTimestamp}.{$payload}";
// Compute signature
$secretBytes = base64_decode(str_replace('whsec_', '', $secret));
$expectedSignature = base64_encode(
hash_hmac('sha256', $signedPayload, $secretBytes, true)
);
// Extract v1 signature
foreach (explode(' ', $msgSignature) as $sig) {
[$version, $signature] = explode(',', $sig, 2);
if ($version === 'v1' && $signature === $expectedSignature) {
return true;
}
}
throw new Exception('Invalid signature');
}Retry Behavior
Notifuse automatically retries failed webhook deliveries with an exponential backoff strategy.
Retry Schedule
A delivery gets up to 10 attempts, the last one about 10 hours after the first:
| Attempt | Delay After Previous |
|---|---|
| 1 | Immediate |
| 2 | 30 seconds |
| 3 | 1 minute |
| 4 | 2 minutes |
| 5 | 5 minutes |
| 6 | 15 minutes |
| 7 | 30 minutes |
| 8 | 1 hour |
| 9 | 2 hours |
| 10 | 6 hours |
If the 10th attempt fails too, the delivery is marked failed and is not retried again.
Success Criteria
A webhook delivery is considered successful if your endpoint returns HTTP status code 2xx (200-299).
Failure Conditions
A delivery attempt fails if:
- Your endpoint returns a non-2xx status code
- Your endpoint takes more than 10 seconds to respond
- The endpoint is unreachable (DNS error, connection refused, etc.)
Automatic Disabling
An endpoint that has moved, been decommissioned or lost its DNS record never comes back on its own, and Notifuse will not keep queueing deliveries for it forever.
After a long run of back-to-back failures, a subscription is switched off automatically and the reason is recorded on it, so a webhook you find disabled can be told apart from one you disabled yourself. The counter is per subscription and a single successful delivery resets it to zero, so an endpoint that is merely having a bad afternoon is not switched off — only one that fails persistently.
Two responses are treated specially:
429 Too Many Requestsnever counts as a failure. Rate limiting is your server asking for less, not an endpoint dying, and a workspace busy enough to be throttled should not have its integration switched off for being busy. The delivery is retried on the normal schedule.410 Goneis terminal on the first response. It is the standard way for a receiver to say “this subscription is dead, stop sending”, so the subscription is retired immediately rather than after the usual run of failures. A subscription you created is switched off with that reason recorded; one created by another tool, such as Zapier, is removed outright, because the tool recreates it when it needs it.404is not treated this way — an endpoint that is briefly missing is retried like any other failure.
To bring a disabled subscription back, fix the endpoint and re-enable it.
A disabled subscription drops events rather than queueing them. Deliveries that come up while a subscription is off — whether you switched it off or Notifuse did — are marked failed in the delivery log and are not replayed when you turn it back on. If you need the events that occurred during an outage, read them from the API rather than expecting a backlog.
Deleting a Subscription
Deleting a subscription also discards the deliveries still queued for it. There is nothing left behind to retry, and no need to drain a queue before deleting.
Disable a subscription instead of deleting it when you expect to bring the endpoint back: disabling is reversible, and the subscription — with its signing secret and its delivery history — survives. A deleted subscription cannot be restored, and recreating it issues a new signing secret.
Best Practices
Return 2xx Quickly
Return a successful response as quickly as possible. Process the webhook payload asynchronously if needed:
// Good: Acknowledge quickly, process later
app.post('/webhooks/notifuse', async (req, res) => {
// Quickly validate signature
verifyWebhook(req.body, req.headers, SECRET);
// Queue for async processing
await queue.add('process-webhook', req.body);
// Respond immediately
res.status(200).json({ received: true });
});
Handle Duplicate Deliveries
Webhooks may be delivered more than once in rare cases. Use the webhook-id header to implement idempotency:
app.post('/webhooks/notifuse', async (req, res) => {
const webhookId = req.headers['webhook-id'];
// Check if we've already processed this webhook
if (await hasProcessed(webhookId)) {
return res.status(200).json({ received: true, duplicate: true });
}
// Mark as processed before handling
await markProcessed(webhookId);
// Process the webhook
await processWebhook(req.body);
res.status(200).json({ received: true });
});
Verify Signatures
Always verify webhook signatures in production to ensure requests are from Notifuse.
Monitor Delivery Failures
In the console, Settings → Webhooks shows each subscription’s success rate over the last 7 days and its last successful delivery. Open a subscription to see how many deliveries succeeded and failed over the last 24 hours or 7 days, and choose View deliveries to list them in the logs.
Through the API, add status (pending, delivering, delivered or failed) to list only the deliveries in that status; any other value answers 400. failed also holds the deliveries waiting for a retry, which move back to delivering when they are sent again, so a delivery listed as failed may still succeed:
curl "https://your-instance.com/api/webhookSubscriptions.deliveries?workspace_id=ws_123&subscription_id=whsub_456&status=failed" \
-H "Authorization: Bearer YOUR_API_KEY"
Testing Webhooks
Send a Test Webhook
Use the test endpoint to verify your webhook configuration:
curl -X POST "https://your-instance.com/api/webhookSubscriptions.test" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "your_workspace",
"id": "whsub_a1b2c3d4e5f6",
"event_type": "contact.created"
}'
The event_type parameter is optional. If provided, the test webhook will include a realistic sample payload for that event type. If omitted, a generic test payload is sent.
Local Development
For local development, use tools like ngrok or localtunnel to expose your local server:
# Start ngrok
ngrok http 3000
# Use the ngrok URL as your webhook endpoint
# https://abc123.ngrok.io/webhooks/notifuse
Permissions
Outgoing subscriptions follow the Webhook Subscriptions permission: read lists subscriptions, opens one, and shows its delivery history — including each event payload and the endpoint’s response status and body. Write creates, updates, deletes, enables and disables subscriptions, and fires a test delivery. Firing a test is a write, not a read, because it makes your server call out.
Incoming provider callbacks follow the Webhook Events permission: read shows the raw callbacks your email providers have sent back to Notifuse, including recipient addresses and provider diagnostics. Webhook Events write gates nothing today — the rows arrive on the provider callback routes, which carry no session and consult no permission, so granting it confers nothing. The console shows it granted and locked.
The catalogue of available event types is not gated at all: any authenticated member or key can list it.
Two actions stay reserved for the workspace owner, whatever permissions a member or API key holds:
- Regenerating a subscription’s signing secret. The secret is also hidden from everyone but the owner, so Webhook Subscriptions read never hands it out — a member can list subscriptions and inspect deliveries without ever seeing the key those payloads are signed with.
- Registering webhooks with an email provider, because it uses the provider credentials stored in your integration.
Webhook Subscriptions write reaches further than its name suggests. A subscription chooses the events it receives, so whoever holds this permission can subscribe to contact and email events and have that data delivered to a URL of their choosing. Grant it as you would grant read access to the contacts and the message history behind those events.
Notes
- Webhooks require HTTPS endpoints in production
- The signing secret is generated automatically when you create a subscription
- Use
webhookSubscriptions.regenerateSecretto rotate the signing secret - See API Reference for complete endpoint documentation