Setting Up Outgoing Webhooks

Create webhook endpoints and select event types

Setting Up Outgoing Webhooks

Outgoing webhooks let Mailnaptic push real-time event notifications to your own server or third-party services. Whenever something happens in your account — a contact subscribes, an email bounces, a campaign sends — Mailnaptic sends an HTTP POST request to your configured endpoint with details about the event.

Creating a webhook endpoint

Navigate to Organization → Webhooks.
Click Add Endpoint.
Enter the URL of your endpoint. This must be an HTTPS URL that accepts POST requests.
Give the endpoint a descriptive name (e.g., "CRM sync" or "Analytics pipeline").
Select the event types you want to subscribe to.
Click Save.

Available event types

Event	Fires when
`contact.created`	A new contact is added to your account
`contact.updated`	A contact's fields are modified
`contact.deleted`	A contact is removed
`contact.subscribed`	A contact opts in to a list
`contact.unsubscribed`	A contact unsubscribes
`email.sent`	An email is successfully sent
`email.delivered`	Delivery confirmed by the receiving server
`email.opened`	An open is tracked
`email.clicked`	A link click is tracked
`email.bounced`	An email bounces (hard or soft)
`email.complained`	A spam complaint is received
`campaign.sent`	A campaign finishes sending

Payload format

Each webhook delivery sends a JSON payload via HTTP POST:

{
  "event": "contact.subscribed",
  "timestamp": "2026-03-18T14:30:00Z",
  "data": {
    "contact_id": 12345,
    "email": "jane@example.com",
    "list_id": 8,
    "list_name": "Newsletter"
  }
}

The Content-Type header is always application/json. Your endpoint should return a 2xx status code to acknowledge receipt.

Retry policy

If your endpoint returns a non-2xx status or the request times out (after 10 seconds), Mailnaptic retries with exponential backoff:

1st retry: 1 minute after failure
2nd retry: 5 minutes
3rd retry: 30 minutes
4th retry: 2 hours
5th retry: 12 hours

After 5 failed attempts, the delivery is marked as permanently failed. You can view failed deliveries in the webhook delivery logs.

Security

Each webhook endpoint is assigned a signing secret displayed once at creation. Mailnaptic includes a X-Mailnaptic-Signature header on every delivery, computed as an HMAC-SHA256 of the request body using this secret. Verify the signature on your server to ensure payloads are authentic.

Best practice: Start by subscribing to a small set of events and expand as needed. Subscribing to every event type can generate significant traffic for high-volume accounts.

Setting Up Outgoing Webhooks