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/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

EventWhen
email.queuedThe API or SMTP ingress accepted an email
email.sentA provider accepted the email
email.deliveredThe provider reported delivery to the recipient's server
email.deferredSending was postponed, for example until a quota resets
email.failoverA provider failed and the email moved to the next provider
email.failedEvery eligible provider failed, or the email could not be sent
email.bouncedThe recipient's server rejected the email
email.complainedThe recipient marked the email as spam
email.openedThe recipient opened the email (open tracking)
email.clickedThe recipient clicked a tracked link
email.unsubscribedThe recipient unsubscribed
email.suppressedA recipient was skipped because the address is on the suppression list
email.receivedInbound mail arrived in an inbox mailbox
connection.unhealthyA provider connection returned repeated errors and is skipped until its circuit breaker closes (data.circuitOpenUntil)
quota.lowA connection reached 90% of its daily limit (once per connection per day)
form.submittedA signup form submission was accepted (data.formId, submissionId, status, contactId). See Signup forms
campaign.pausedA safeguard paused a sending campaign because of its bounce or complaint rate (data.campaignId, code, reason, value, threshold, sample). See Deliverability safeguards
campaigns.blockedThe workspace guard started holding new campaigns (data.code, reason, bounceRate, complaintRate)
form.confirmedA double opt-in subscription was confirmed (data.formId, submissionId, contactId, listIds)
automation.completedA contact went through every step of an automation (data.automationId, automationName, runId, contactId, version). See Automations
automation.exitedA contact left an automation early (the same, plus reason: goal, exit_step, exit_condition, unsubscribed, …)
campaign.ab_winnerThe 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:

HeaderValue
Content-Typeapplication/json
User-AgentOneSend-Webhooks/1.0
X-OneSend-EventThe event type, for example email.bounced
X-OneSend-TimestampUnix time in seconds when the request was signed
X-OneSend-Signaturev1=<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:

  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):

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 id to deduplicate and createdAt to order.
  • Each endpoint receives events as separate requests; there is no batching.