Features

Webhooks

Receive real-time HTTP callbacks when events occur in your workspace.

Overview

Notifuse handles two types of webhooks:

  1. 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.

  2. 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
Settings, Webhooks: two endpoints with their events and delivery success rate

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:

The event types of a webhook endpoint, chosen by checkbox, with Select all

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

EventDescription
contact.createdA new contact was added to the workspace
contact.updatedContact data was modified
contact.deletedA contact was permanently deleted

List Events

EventDescription
list.subscribedContact subscribed to a list
list.unsubscribedContact unsubscribed from a list
list.confirmedContact confirmed double opt-in subscription
list.resubscribedPreviously unsubscribed contact resubscribed
list.bouncedEmail to contact bounced
list.complainedContact marked email as spam
list.pendingContact subscription is awaiting confirmation
list.removedContact was removed from list

Segment Events

EventDescription
segment.joinedContact entered a segment (matched segment criteria)
segment.leftContact left a segment (no longer matches criteria)

Email Events

EventDescription
email.sentEmail was sent to contact
email.deliveredEmail delivery was confirmed by the recipient’s server
email.openedContact opened the email
email.clickedContact clicked a link in the email
email.bouncedEmail delivery failed
email.complainedContact marked email as spam
email.unsubscribedContact unsubscribed via email link

Custom Events

EventDescription
custom_event.createdA new custom event was recorded
custom_event.updatedA custom event was updated
custom_event.deletedA 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_ids applies to the list.* events only, segment_ids to the segment.* 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:

FieldDescription
enabledWhether the subscription is currently delivering
sourceWhat created it. Absent for a subscription you created yourself; zapier for one created by the Zapier integration
consecutive_failuresDelivery attempts that have failed back to back. Reset to zero by the first success
failing_sinceWhen the current run of failures started. Cleared by the first success
disabled_reasonWhy the subscription was switched off automatically. Absent for one you switched off yourself
last_delivery_atWhen 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
  }
}
FieldDescription
idUnique identifier for the webhook delivery
typeThe event type that triggered the webhook
timestampISO 8601 timestamp when the webhook was sent
workspace_idThe workspace where the event occurred
dataEvent-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:

HeaderDescription
webhook-idUnique identifier for the webhook delivery
webhook-timestampUnix timestamp when the webhook was sent
webhook-signatureHMAC-SHA256 signature of the payload

Verifying the Signature

  1. Extract the timestamp and signature from the headers
  2. Construct the signed payload: {webhook-id}.{webhook-timestamp}.{body}
  3. Compute HMAC-SHA256 using your webhook secret
  4. 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:

AttemptDelay After Previous
1Immediate
230 seconds
31 minute
42 minutes
55 minutes
615 minutes
730 minutes
81 hour
92 hours
106 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 Requests never 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 Gone is 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. 404 is 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.regenerateSecret to rotate the signing secret
  • See API Reference for complete endpoint documentation