All articles › Webhooks & Integrations

Setting Up Outgoing Webhooks

Create webhook endpoints and select event types

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

  1. Navigate to Organization → Webhooks.
  2. Click Add Endpoint.
  3. Enter the URL of your endpoint. This must be an HTTPS URL that accepts POST requests.
  4. Give the endpoint a descriptive name (e.g., "CRM sync" or "Analytics pipeline").
  5. Select the event types you want to subscribe to.
  6. 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.

Was this helpful?

Copy for AI (Markdown)

Related articles

Mailnaptic · Help center