Skip to content
Invitation-only alpha. Features and limits may change as we learn from testing.

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.

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.

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.

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.

Every request has three headers: Webhook-Id, Webhook-Timestamp (Unix seconds) and Webhook-Signature (v1, followed by the signature).

  1. Decode the secret from base64 into 32 bytes.
  2. Take the raw request body, before any JSON parsing.
  3. Compute HMAC-SHA256 over Webhook-Id + "." + Webhook-Timestamp + "." + raw body, and encode it in base64.
  4. 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.
  5. Reject timestamps more than five minutes from your clock.
  6. Skip events whose Webhook-Id you’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));
}
  • Reply with any 2xx to 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-Id and body, with a new timestamp and signature.
  • Reply 410 Gone to 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.

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.