Skip to main content

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
Outgoing webhooks screenshot

Creating a Webhook Subscription

Create a webhook subscription via the API or the Notifuse console:

Available Event Types

Contact Events

List Events

Segment Events

Email Events

Custom Events

Custom Event Filters

For custom events, you can optionally filter by goal_types and event_names:

Payload Structure

All webhook payloads follow this structure:

Example: Contact Created

Example: Email Sent

Example: Email Opened

Example: Segment Joined

Verifying Webhook Signatures

Notifuse signs all webhook payloads using the Standard Webhooks specification with HMAC-SHA256.

Headers

Each webhook request includes these headers:

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

Retry Behavior

Notifuse automatically retries failed webhook deliveries with an exponential backoff strategy.

Retry Schedule

Webhooks are retried up to 10 times over approximately 34 hours:

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
  • The request times out (30 second timeout)
  • The endpoint is unreachable (DNS error, connection refused, etc.)

Best Practices

Return 2xx Quickly

Return a successful response as quickly as possible. Process the webhook payload asynchronously if needed:

Handle Duplicate Deliveries

Webhooks may be delivered more than once in rare cases. Use the webhook-id header to implement idempotency:

Verify Signatures

Always verify webhook signatures in production to ensure requests are from Notifuse.

Monitor Delivery Failures

Use the Notifuse console or API to monitor webhook delivery status:

Testing Webhooks

Send a Test Webhook

Use the test endpoint to verify your webhook configuration:
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:

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