Webhooks
A webhook sends an HTTPS POST to your server when something happens to one of your messages, so
your application doesn’t have to poll the API.
Endpoints are set up by weneed on request; write to help@weneed.email with your HTTPS URL and the events you need. Once enabled, the service delivers notifications automatically.
Events
Section titled “Events”| Event | Sent when |
|---|---|
email.accepted |
weneed.email stored the message. |
email.submitted |
The message was handed to the recipient’s server. |
email.delivered |
The recipient’s server accepted it. |
email.bounced |
The recipient’s server rejected it, at once or later. |
email.complained |
The recipient marked it as spam. |
email.rejected |
It couldn’t be sent and won’t be retried. |
email.suppressed |
It wasn’t sent because the address is suppressed. |
email.expired |
Its expires_at passed before it could be sent. |
email.cancelled |
It was cancelled before sending. |
email.submission_unknown |
It can’t be told whether the recipient’s server took it. |
email.delivery_delayed |
The recipient’s server reported a temporary delay and keeps trying. This is not a delivery. |
domain.status_changed |
One of your sending domains stopped passing a check, or recovered. |
Events carry metadata only. They never include the subject, body, recipient address or headers. New fields and event types may be added; ignore ones you don’t know.
Payload
Section titled “Payload”Every event has the same envelope. The body is the exact bytes that were stored when the event was recorded: a retry or replay sends them unchanged, so the signature stays valid.
{ "id": "0f8c…", "type": "email.bounced", "api_version": "v1", "occurred_at": "2026-10-15T10:00:00.123Z", "received_at": "2026-10-15T10:00:01.456Z", "project_id": "5b1e…", "simulated": false, "data": { "email_id": "7d2a…", "submission_state": "submitted", "recipient_outcome": "bounced", "reason": null, "tags": { "order": "1234" }, "attempt_number": 1, "feedback": { "action": "failed", "status": "5.1.1" } }}For email.* events, data holds the message’s facts at the moment the event was recorded:
| Field | Meaning |
|---|---|
email_id |
The message ID returned by POST /v1/emails. |
submission_state |
The submission state at that moment. |
recipient_outcome |
pending, delivered_to_server, delivery_unknown, bounced, suppressed or rejected, or null if none was recorded. |
reason |
Why the message is in that state: code, category (wait, fix, contact_support, none) and retry (safe_same_key, do_not_resend, not_applicable). null when the state has no cause. See Reason codes. |
tags |
The tags you sent with the message, or null when historical tags were not retained. |
attempt_number |
The sending attempt the event concerns, or null before the first attempt. |
feedback |
Only on email.bounced: the delivery report’s action and enhanced status code, or null if no report was received. |
Each event describes its own moment. A later event can carry newer facts, and events can arrive out
of order: use occurred_at, or read GET /v1/emails/{id} for the current
state.
For domain.status_changed, data has domain_id, status (degraded or recovered) and the
cause, one of domain_revoked, ownership_stale, authentication_stale,
authentication_failed or preparation_pending. It carries no DNS values; open the project in
Control for the details.
Events recorded before these fields existed carry only data.email_id, and replays of them stay
that way.
Get the signing secret
Section titled “Get the signing secret”Open your project’s Webhook settings. On the endpoint, reveal the signing secret. This asks for your authenticator code and works once: tick that you’re ready to store it, reveal it, and store it in your receiver’s secret store straight away.
If the page didn’t load and the secret is lost, write to help@weneed.email to have the endpoint disabled and recreated.
Verify each request
Section titled “Verify each request”Every request has three headers: Webhook-Id, Webhook-Timestamp (Unix seconds) and
Webhook-Signature (v1, followed by the signature).
- Decode the secret from base64 into 32 bytes.
- Take the raw request body, before any JSON parsing.
- Compute HMAC-SHA256 over
Webhook-Id + "." + Webhook-Timestamp + "." + raw body, and encode it in base64. - Compare it with the signature after
v1,, using a constant-time comparison. While a secret is being replaced, the header can carry two signatures separated by a space; accept either. - Reject timestamps more than five minutes from your clock.
- Skip events whose
Webhook-Idyou’ve already processed.
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(rawBody, headers, secretBase64) { const id = headers['webhook-id']; const timestamp = headers['webhook-timestamp']; if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; const expected = createHmac('sha256', Buffer.from(secretBase64, 'base64')) .update(`${id}.${timestamp}.`) .update(rawBody) .digest(); return headers['webhook-signature'] .split(' ') .filter((part) => part.startsWith('v1,')) .map((part) => Buffer.from(part.slice(3), 'base64')) .some((sig) => sig.length === expected.length && timingSafeEqual(sig, expected));}Responses and retries
Section titled “Responses and retries”- Reply with any
2xxto confirm. Respond within 10 seconds. - Any other reply or a timeout is retried after about 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours, 24 hours and 48 hours, for at most 72 hours.
- A retry has the same
Webhook-Idand body, with a new timestamp and signature. - Reply
410 Goneto disable the endpoint.
The same event can arrive more than once, and events can arrive out of order. A webhook is never a reason to resend an email.
History and disabling
Section titled “History and disabling”View webhook history lists each delivery with its latest attempt and outcome. Failed deliveries also show on your project home.
To stop deliveries, select Review disabling this endpoint and confirm. Pending notifications are held. One already in progress may still arrive.