---
title: "Webhooks"
description: "OneSend sends events to your endpoints as they happen: sends, deliveries, bounces, opens, clicks, received mail and provider problems. An endpoint is an HTTPS URL in your app, or a Slack or Discord incoming-webhook URL."
url: https://onesend.email/docs/webhooks/
---
# Webhooks

OneSend sends events to your endpoints as they happen: sends, deliveries, bounces, opens, clicks, received mail and provider problems. An endpoint is an HTTPS URL in your app, or a Slack or Discord incoming-webhook URL.

Provider webhooks are separate: OneSend registers its own `/hooks/<provider>/<connection id>/<token>` URL with each provider that supports it, to receive their events. The URL is returned as `webhookUrl` by `GET /v1/connections/{id}`; copy it from there when a provider needs it entered by hand. This page covers outgoing webhooks from OneSend to you.

## Create an endpoint

In the dashboard, open **Developers → Webhooks** and select **Add endpoint** (admins and the owner). With the API, use an **Admin** key: webhooks are configuration, so a Full access or Sending only key gets 403 `insufficient_scope`. Admins and owners create one under **API keys → Create key → Permission: Admin**.

```bash
curl -X POST http://localhost:3000/v1/webhooks \
  -H "Authorization: Bearer $ONESEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://app.example.com/hooks/onesend","events":["email.delivered","email.bounced","email.complained"]}'
```

```json
{ "id": "wh_…", "url": "https://app.example.com/hooks/onesend", "events": ["email.delivered", "email.bounced", "email.complained"], "kind": "http", "enabled": true, "createdAt": "…", "secret": "whsec_…" }
```

The `secret` is returned only in this response. Store it with your app's other secrets; you need it to verify signatures. To replace it, call `POST /v1/webhooks/{id}/rotate-secret`; the response contains the new secret once, and deliveries are signed with it immediately.

`events` defaults to `["*"]` (all events). The `email.` prefix is optional in the request; the response always shows the full event names. Slack (`hooks.slack.com`) and Discord (`discord.com/api/webhooks`) URLs are detected automatically, or set `"kind": "slack"` or `"kind": "discord"`.

<a id="local-receivers"></a>
Endpoints on `localhost`, private networks or link-local addresses are refused by default, to prevent server-side request forgery: creating one (or a mailbox `webhookUrl`) returns 400 `unsafe_url`. To test with a receiver on your own machine, start the server with `ONESEND_ALLOW_PRIVATE_NETWORK=true`, or expose the receiver through a public HTTPS tunnel.

Other endpoints:

- `GET /v1/webhooks` lists endpoints (without secrets). Each has `status` and `statusReason`; `secret_unreadable` means the signing secret can no longer be decrypted (for example after `ONESEND_SECRET` changed without `ONESEND_SECRET_PREVIOUS`), and nothing is delivered until you rotate the secret.
- `POST /v1/webhooks/{id}/rotate-secret` returns a new signing secret once.
- `POST /v1/webhooks/{id}/test` sends a test event now and returns `{ "ok": true, "error": null }`, or `"ok": false` with the error.
- `DELETE /v1/webhooks/{id}` deletes an endpoint.

## Events

| Event | When |
|---|---|
| `email.queued` | The API or SMTP ingress accepted an email |
| `email.sent` | A provider accepted the email |
| `email.delivered` | The provider reported delivery to the recipient's server |
| `email.deferred` | Sending was postponed, for example until a quota resets |
| `email.failover` | A provider failed and the email moved to the next provider |
| `email.failed` | Every eligible provider failed, or the email could not be sent |
| `email.bounced` | The recipient's server rejected the email |
| `email.complained` | The recipient marked the email as spam |
| `email.opened` | The recipient opened the email (open tracking) |
| `email.clicked` | The recipient clicked a tracked link |
| `email.unsubscribed` | The recipient unsubscribed |
| `email.suppressed` | A recipient was skipped because the address is on the suppression list |
| `email.received` | Inbound mail arrived in an inbox mailbox |
| `connection.unhealthy` | A provider connection returned repeated errors and is skipped until its circuit breaker closes (`data.circuitOpenUntil`) |
| `quota.low` | A connection reached 90% of its daily limit (once per connection per day) |
| `form.submitted` | A signup form submission was accepted (`data.formId`, `submissionId`, `status`, `contactId`). See [Signup forms](https://onesend.email/docs/forms-and-archive/#webhook-events) |
| `campaign.paused` | A safeguard paused a sending campaign because of its bounce or complaint rate (`data.campaignId`, `code`, `reason`, `value`, `threshold`, `sample`). See [Deliverability safeguards](https://onesend.email/docs/deliverability/#automatic-campaign-pause) |
| `campaigns.blocked` | The workspace guard started holding new campaigns (`data.code`, `reason`, `bounceRate`, `complaintRate`) |
| `form.confirmed` | A double opt-in subscription was confirmed (`data.formId`, `submissionId`, `contactId`, `listIds`) |
| `automation.completed` | A contact went through every step of an automation (`data.automationId`, `automationName`, `runId`, `contactId`, `version`). See [Automations](https://onesend.email/docs/automations/#webhook-events) |
| `automation.exited` | A contact left an automation early (the same, plus `reason`: `goal`, `exit_step`, `exit_condition`, `unsubscribed`, …) |
| `campaign.ab_winner` | The winning variant of a campaign A/B test was sent to the rest of the recipients (`data.campaignId`, `variantId`, `variantName`, `decidedBy`, `remainder`). See [A/B testing](https://onesend.email/docs/marketing/#ab-testing) |

Slack and Discord endpoints receive a readable message for failures, bounces, complaints, deferrals, failovers, received mail and low quota, plus any event you list explicitly.

## Payload

HTTP endpoints receive a `POST` with a JSON body:

```json
{
  "id": "evt_01JC…",
  "type": "email.bounced",
  "createdAt": "2026-11-08T10:15:00.000Z",
  "data": {
    "messageId": "msg_01JC…",
    "provider": "resend",
    "connectionId": "con_…",
    "recipient": "ada@example.com"
  }
}
```

`data` can include more fields depending on the event, such as a bounce `code` or `reason`. Every `email.*` event about a message has `data.recipient` (the first recipient for events that cover the whole message, such as `email.queued` and `email.sent`). Use `id` to ignore duplicate deliveries.

The event sent by `POST /v1/webhooks/{id}/test` is an `email.sent` event with `data.recipient: "test@example.com"` and `data.test: true`; no email is sent. Ignore events with `data.test` in your processing.

Request headers:

| Header | Value |
|---|---|
| `Content-Type` | `application/json` |
| `User-Agent` | `OneSend-Webhooks/1.0` |
| `X-OneSend-Event` | The event type, for example `email.bounced` |
| `X-OneSend-Timestamp` | Unix time in seconds when the request was signed |
| `X-OneSend-Signature` | `v1=<hex>`, the HMAC-SHA256 signature described below |

<a id="verifying-signatures"></a>
## Verify signatures

Each HTTP delivery is signed with the endpoint secret:

```
signature = hex( HMAC-SHA256( key = endpoint secret, message = timestamp + "." + raw request body ) )
X-OneSend-Signature: v1=<signature>
```

Until 2027-03-01 every delivery also carries the same values under the names from before the OneSend rename (`X-OpenEmail-Signature`, `X-OpenEmail-Timestamp`, `X-OpenEmail-Event`, and `X-OpenEmail-Delivery` for automation steps), for receivers written for OneSend. They are removed in the first release after that date: read the `X-OneSend-*` headers. The same applies to automation webhook steps and inbound mail webhooks.

To verify a request:

1. Read the raw request body as bytes, before any JSON parsing. Parsing and re-serializing the JSON changes the bytes and breaks the signature.
2. Compute the HMAC over `X-OneSend-Timestamp`, a `.`, and the raw body, using the full secret (including the `whsec_` prefix) as the key.
3. Compare it with the value after `v1=` using a constant-time comparison.
4. Reject the request if the timestamp is more than 5 minutes from your server's clock, to limit replay.

Node.js (Express):

```js
import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';

const secret = process.env.ONESEND_WEBHOOK_SECRET; // whsec_…
const app = express();

app.post('/hooks/onesend', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('x-onesend-timestamp') ?? '';
  const signature = req.get('x-onesend-signature') ?? '';
  const expected = 'v1=' + createHmac('sha256', secret).update(`${timestamp}.`).update(req.body).digest('hex');

  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
  const valid = signature.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  if (!fresh || !valid) return res.status(400).send('invalid signature');

  const event = JSON.parse(req.body.toString('utf8'));
  // handle event.type and event.data, using event.id to skip duplicates
  res.sendStatus(204);
});
```

Python:

```python
import hashlib, hmac, time

def verify(secret: str, timestamp: str, signature: str, raw_body: bytes) -> bool:
    if abs(time.time() - int(timestamp or 0)) > 300:
        return False
    mac = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256)
    return hmac.compare_digest("v1=" + mac.hexdigest(), signature)
```

Slack and Discord deliveries are not signed, because those services do not verify signatures.

## Delivery and retries

- Return any 2xx status within 10 seconds to acknowledge a delivery. Do slow work after responding.
- Any other status, a timeout or a connection error is retried with exponential backoff: about 2, 4, 8, 16, 32 and 64 seconds, then 2, 4 and 8.5 minutes, for 10 attempts over roughly 17 minutes. After the last attempt the delivery is dropped and a warning is logged on the server.
- Deliveries can arrive more than once and out of order. Use the event `id` to deduplicate and `createdAt` to order.
- Each endpoint receives events as separate requests; there is no batching.
