# Webhooks {#webhooks}


A webhook tells your application what happened without polling. Nitrosend
POSTs a signed event to your HTTPS endpoint when a transactional email is
accepted, delivered, bounced, complained about, opened, clicked or fails for
good, when a reply reaches one of your brand's inboxes, and when something
changes on the account: a campaign finishes, sending pauses, a domain is
verified.

Email events cover transactional email: single messages your brand sends, not
campaigns or flows. SMS and test sends do not emit email events.


## Email events {#email-events}


| Event | Sent when |
| --- | --- |
| `email.sent` | The provider accepted the message. |
| `email.delivered` | The recipient's mail server accepted it. |
| `email.bounced` | It bounced, hard or soft. |
| `email.complained` | The recipient marked it as spam. |
| `email.opened` | The first time it was opened. Security scanners and bots do not count. |
| `email.clicked` | The first human click of each link in it. |
| `email.failed` | It failed for good. A failure Nitrosend is still retrying is not reported, and a send whose provider outcome is unknown reports once that outcome is known. |
| `email.received` | A message reached one of the brand's inboxes and was not quarantined: a reply, an automatic reply, or new mail to the inbox address. See [Replies](#replies). |

Opens and clicks come from Nitrosend's own tracking, so a brand that
[turns open or click tracking off](https://docs.nitrosend.com/guides/sending-emails.md#open-and-click-tracking)
stops sending those two events.


## Account events {#account-events}


| Event | Sent when |
| --- | --- |
| `campaign.completed` | A campaign finished sending to its whole audience. |
| `campaign.failed` | A campaign send ended before reaching any recipient. |
| `campaign.stopped` | Nitrosend paused a campaign send because its bounce or spam-complaint rate crossed the stop threshold. |
| `flow.paused` | Nitrosend paused a flow because its bounce or spam-complaint rate crossed the pause threshold. |
| `sending.paused` | Nitrosend paused all sending on the account. |
| `sending.limit_approaching` | The account has used most of its rolling 24-hour sending allowance. |
| `sending.limit_reached` | The account has used its whole rolling 24-hour allowance; sends wait for capacity. |
| `import.completed` | A contact import finished. |
| `import.failed` | A contact import failed. |
| `domain.verified` | A sending domain passed DNS verification and can send. |
| `domain.verification_lost` | A verified sending domain failed its DNS checks and is no longer verified. |
| `domain.dns_degraded` | A verified sending domain's DNS records could not be confirmed; it stays verified while Nitrosend rechecks. |
| `webhook.disabled` | Nitrosend turned off one of the brand's webhooks after three days of failed deliveries. |

The three `sending.*` events reach the webhooks of every brand in the account;
the others reach the webhooks of the brand they concern. The
[API Reference](https://docs.nitrosend.com/api.md) lists each event's fields.


## Add an endpoint {#add-an-endpoint}


In the dashboard, open **Settings > Webhooks** and choose **New Webhook**
([app.nitrosend.com/my/settings/webhooks](https://app.nitrosend.com/my/settings/webhooks)).
Enter the endpoint URL and pick the events it should receive. Settings lists
the email events; add account events through the API.

Or create it with the API:

```bash
curl -X POST https://api.nitrosend.com/v1/my/webhooks \
  -H "Authorization: Bearer $NITROSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/nitrosend",
    "events": ["email.delivered", "email.bounced", "email.complained", "email.failed"]
  }'
```

The response includes the endpoint's signing secret (`whsec_...`) in full.
Store it with your other secrets. Later reads mask it; reveal it again from the
dashboard or with `GET /v1/my/webhooks/{id}?reveal=true`.

The URL must use HTTPS, resolve to a public internet address, and carry no
credentials. A brand can have up to 10 webhooks. Webhooks appear in Settings
only for people who can manage API keys.


## What a request looks like {#what-a-request-looks-like}


Each event is one `POST` with a JSON body:

```http
POST /webhooks/nitrosend HTTP/1.1
Content-Type: application/json
User-Agent: Nitrosend-Webhooks/1.0
webhook-id: evt_0192f3a4-7b1c-7d2e-9f10-2a3b4c5d6e7f
webhook-timestamp: 1790740800
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{
  "type": "email.bounced",
  "timestamp": "2026-09-30T10:00:00.000Z",
  "data": {
    "message_id": 48213,
    "to": "ada@example.com",
    "subject": "Reset your password",
    "idempotency_key": "reset-8841",
    "tags": { "user_id": "42" },
    "bounce": { "type": "hard", "subtype": "NoEmail" }
  }
}
```

- `message_id` is the `id` that `POST /v1/my/messages` returned.
- `idempotency_key` is the `Idempotency-Key` you sent the message with. It is
  left out when you sent none.
- `tags` are the tags you sent the message with.
- `timestamp` is when the event happened.
- Some events add detail, such as `bounce` on `email.bounced` or `failure`
  on `email.failed`. The [API Reference](https://docs.nitrosend.com/api.md) lists every event's fields.


## Replies {#replies}


`email.received` reports mail that reaches one of your brand's inboxes. Inboxes
are part of the [Agent Inbox](https://docs.nitrosend.com/guides/agent-inbox.md). A reply reaches Nitrosend when it is sent to an inbox address, so send
with that address as `reply_to` (or `from`) when you want replies reported.

```json
{
  "type": "email.received",
  "timestamp": "2026-09-30T10:04:12.000Z",
  "data": {
    "message_id": 48213,
    "idempotency_key": "receipt-77",
    "tags": { "order": "77" },
    "from": "ada@example.com",
    "to": "support@yourbrand.com",
    "subject": "Re: Your receipt",
    "text": "Can I change the delivery address?",
    "html": "<p>Can I change the delivery address?</p>",
    "truncated": false,
    "auto_submitted": false,
    "attachments": [
      {
        "id": 311, "filename": "photo.jpg", "size": 48213,
        "content_type": "image/jpeg", "scanned": true,
        "scan_status": "clean", "downloadable": true,
        "download_requires_confirmation": false
      },
      {
        "id": 312, "filename": "site-visit.mov", "size": 31457280,
        "content_type": "video/quicktime", "scanned": false,
        "scan_status": "failed", "downloadable": false,
        "download_requires_confirmation": false,
        "availability_reason": "too_large"
      }
    ],
    "conversation_id": 9021,
    "conversation_message_id": 55410
  }
}
```

- When the message answers one of your sends, `message_id`, `idempotency_key`
  and `tags` identify that send, as they do on every other event. Otherwise
  `message_id` is `null` and `tags` is empty.
- `text` and `html` are each capped at 64 KiB; `truncated` is `true` when
  either was cut. The full message stays in the inbox.
- `attachments` lists every file the message carried, without their contents,
  including files Nitrosend kept back. Download a file only when its
  `downloadable` is `true`:

  ```text
  GET /v1/my/conversations/{conversation_id}/messages/{conversation_message_id}/attachments/{id}
  ```

  If `download_requires_confirmation` is also `true`, no scan covered the file,
  and it downloads only with `?acknowledge_unscanned=true`.

  When `downloadable` is `false`, the file is not available and the download
  endpoint won't serve it. `availability_reason` says why: for example
  `too_large` (over 25 MB), `message_limit` (the message's files total over
  50 MB), `unsafe` (a threat was found) or `scan_failed`. Treat any other value
  as unavailable too.

  These are the conversation API's attachment fields. `scanned` is `true` only
  for a clean scan verdict; the conversation API doesn't return it. See
  [attachment availability](https://docs.nitrosend.com/guides/agent-inbox.md#read-attachment-availability).
- `attachments_omitted` appears only when the message carried more than 50
  files. It counts the files past that limit, which Nitrosend didn't keep. An
  empty `attachments` list without `attachments_omitted` means the message had
  no files.
- `auto_submitted` is `true` for automatic replies such as out-of-office
  notices.
- Mail the inbox quarantines (spam, viruses, blocked senders) is not sent.
  Each message is reported once.


## Verify the signature {#verify-the-signature}


Requests are signed in the [Standard Webhooks](https://www.standardwebhooks.com)
format, so any Standard Webhooks library can verify them. Verify every request
before acting on it, using the raw body exactly as received.

With the Node SDK:

```ts
import express from 'express';
import { verifyWebhook, WebhookVerificationError } from '@nitrosend/sdk';

const app = express();

// Register this route before any JSON body parser, so the raw body reaches it.
app.post('/webhooks/nitrosend', express.raw({ type: 'application/json' }), async (req, res) => {
  try {
    const event = await verifyWebhook(
      req.body.toString('utf8'),
      req.headers,
      process.env.NITROSEND_WEBHOOK_SECRET!,
    );
    // event.type, event.data.message_id, ...
    res.sendStatus(200);
  } catch (error) {
    if (error instanceof WebhookVerificationError) return res.sendStatus(400);
    throw error;
  }
});
```

Without a library:

1. Base64-decode the part of the secret after `whsec_`. That is the key.
2. Build the signed content: `{webhook-id}.{webhook-timestamp}.{raw body}`.
3. Compute an HMAC-SHA256 of it with the key and base64-encode the result.
4. Compare it, in constant time, with each `v1,` value in `webhook-signature`
   (values are space-separated). Accept the request if one matches.
5. Reject the request if `webhook-timestamp` is more than 5 minutes from now.

```python
import base64, hashlib, hmac, time

def verify(body: bytes, headers, secret: str) -> bool:
    try:
        msg_id = headers["webhook-id"]
        timestamp = int(headers["webhook-timestamp"])
        signatures = headers["webhook-signature"].split(" ")
    except (KeyError, ValueError):
        return False
    if abs(time.time() - timestamp) > 300:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    return any(
        hmac.compare_digest(sig.split(",", 1)[1], expected)
        for sig in signatures
        if sig.startswith("v1,")
    )
```


## Respond, retries and duplicates {#respond-retries-and-duplicates}


Return any `2xx` status within 10 seconds to acknowledge an event. Anything
else is a failed attempt: another status, a timeout, or a redirect, which
Nitrosend does not follow. A failed event is retried after 1 minute,
5 minutes, 30 minutes, 2 hours, 8 hours and 24 hours, then marked failed.

An event can arrive more than once (for example, when your endpoint handled
it but answered too late), and a retried event can arrive after later ones. `webhook-id` stays the same across retries of an event:
record the ids you have handled and skip repeats, and use `timestamp` for
ordering.

When deliveries to an endpoint have failed continuously for 3 days, the next
failed attempt turns the endpoint off and emails the account owner. Events that occur while an endpoint
is off are not sent, including after you turn it back on.


## Test and inspect {#test-and-inspect}


Choose **Send test event** from the webhook's menu, or call
`POST /v1/my/webhooks/{id}/test`, to send a sample event through the same
signed delivery path. A test event has `"test": true` in `data` and its ids are
`null`. The API sends `email.delivered` by default; pass
`{"type": "email.received"}` (or any other event) to test that event's shape.

Each webhook keeps the last 7 days of deliveries, with their status, response
code and attempt count. See them in the webhook's edit dialog, or with
`GET /v1/my/webhooks/{id}/deliveries`.


## API {#api}


| Action | Method | Endpoint |
| --- | --- | --- |
| List webhooks | `GET` | `/v1/my/webhooks` |
| Create a webhook | `POST` | `/v1/my/webhooks` |
| Get a webhook (`?reveal=true` for the full secret) | `GET` | `/v1/my/webhooks/{id}` |
| Change the URL, events, or turn it on or off | `PATCH` | `/v1/my/webhooks/{id}` |
| Delete a webhook and its delivery history | `DELETE` | `/v1/my/webhooks/{id}` |
| Send a test event | `POST` | `/v1/my/webhooks/{id}/test` |
| List recent deliveries | `GET` | `/v1/my/webhooks/{id}/deliveries` |

See the [API Reference](https://docs.nitrosend.com/api.md) for request and response schemas.
