Handling Webhooks

Receive and process webhook event payloads

Handling Webhooks

Webhooks allow Mailnaptic to push real-time event data to your server whenever something important happens — a contact opens an email, clicks a link, bounces, unsubscribes, or files a complaint. Instead of polling the API for changes, your application receives an HTTP POST request the moment an event occurs.

Setting Up a Webhook Endpoint

Before Mailnaptic can send you events, you need a publicly accessible HTTPS URL that can receive POST requests. Navigate to Organization → API Keys and scroll to the Webhook Endpoints section. Click Add Endpoint, enter your URL, and select which event types you want to receive.

Available event types include:

email.delivered — message accepted by the recipient's mail server
email.opened — recipient opened the email (pixel-tracked)
email.clicked — recipient clicked a tracked link
email.bounced — message bounced (includes bounce type: hard or soft)
email.complained — recipient marked the email as spam
contact.unsubscribed — contact opted out via the preference center or one-click unsubscribe
contact.created — a new contact was added to your organization
contact.updated — contact data was modified

Webhook Payload Structure

Each webhook delivery is a JSON POST request with the following structure:

{
  "event": "email.bounced",
  "timestamp": "2026-03-18T14:32:00Z",
  "data": {
    "contact_id": 12345,
    "email": "jane@example.com",
    "campaign_id": 678,
    "bounce_type": "hard",
    "reason": "Mailbox does not exist"
  }
}

The data object varies by event type and contains all the relevant context for that specific occurrence.

Verifying Webhook Signatures

Every webhook request includes an X-Mailnaptic-Signature header. This is an HMAC-SHA256 signature computed from the raw request body using your webhook signing secret. Always verify this signature before processing the payload to ensure the request genuinely came from Mailnaptic.

To verify, compute HMAC-SHA256(raw_body, signing_secret) and compare it to the header value. If they don't match, reject the request with a 401 status.

Responding to Webhooks

Your endpoint should return a 2xx status code within 10 seconds. If Mailnaptic receives a non-2xx response or the request times out, it will retry delivery using exponential backoff — up to 5 retries over approximately 24 hours. After all retries are exhausted, the endpoint is marked as failing and you'll receive an email notification.

Best Practices

Acknowledge immediately: Return 200 right away, then process the event asynchronously in a background job queue. This prevents timeouts.
Handle duplicates: Webhooks may occasionally be delivered more than once. Use the event's unique ID to deduplicate.
Monitor failures: Check the webhook delivery logs in your Organization settings to spot persistent failures early.
Use HTTPS: Mailnaptic only delivers webhooks to secure HTTPS endpoints.

Handling Webhooks