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