Docs / Sending and domains
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.
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"]}'
{ "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".
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/webhookslists endpoints (without secrets). Each hasstatusandstatusReason;secret_unreadablemeans the signing secret can no longer be decrypted (for example afterONESEND_SECRETchanged withoutONESEND_SECRET_PREVIOUS), and nothing is delivered until you rotate the secret.POST /v1/webhooks/{id}/rotate-secretreturns a new signing secret once.POST /v1/webhooks/{id}/testsends a test event now and returns{ "ok": true, "error": null }, or"ok": falsewith 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 |
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 |
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 |
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 |
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:
{
"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 |
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:
- Read the raw request body as bytes, before any JSON parsing. Parsing and re-serializing the JSON changes the bytes and breaks the signature.
- Compute the HMAC over
X-OneSend-Timestamp, a., and the raw body, using the full secret (including thewhsec_prefix) as the key. - Compare it with the value after
v1=using a constant-time comparison. - Reject the request if the timestamp is more than 5 minutes from your server's clock, to limit replay.
Node.js (Express):
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:
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
idto deduplicate andcreatedAtto order. - Each endpoint receives events as separate requests; there is no batching.