Webhooks
Signed HTTPS callbacks when readers subscribe, open, click, bounce, vote and more.
Webhooks send an HTTPS POST to your server when something happens: a reader subscribes, opens, clicks, bounces or votes. Use them to sync your CRM, trigger onboarding in your product, or log engagement in your warehouse.
Add an endpoint
- Open the settingsAn owner goes to Settings → Webhooks and adds an endpoint URL. It must be
https://and publicly reachable; private and internal addresses are refused. - Pick eventsChoose which events this endpoint receives. A newsletter can have up to 10 endpoints.
- Save the signing secretA secret starting with
whsec_is shown once. You can reveal it again later from the endpoint. Use it to verify signatures. - Send a testSend test event delivers a
pingevent, so you can check your handler before real events arrive.
Events
| Event | Sent when |
|---|---|
subscriber.created | A new address joined the list, with any status. |
subscriber.subscribed | An address became subscribed: signup, confirmation, import or API. |
subscriber.unsubscribed | An address unsubscribed or was unsubscribed. |
email.delivered | A campaign email reached the recipient's mail server. |
email.opened | A campaign email was opened (indicative; automatic opens are flagged). |
email.clicked | A tracked link was clicked. Includes the URL. |
email.bounced | A campaign email bounced. Includes the bounce type. |
email.complained | A recipient marked a campaign email as spam. |
campaign.sent | A campaign finished sending. |
poll.voted | A reader voted in a poll, or changed their vote. |
import.completed | A CSV import finished, with how many were added, updated and skipped. |
Payload
Every event has the same envelope. The event-specific details are in data.
{
"id": "evt_k57c2x9w1q8t0m3h4r6p",
"type": "email.clicked",
"createdAt": "2026-11-18T09:41:07.512Z",
"newsletter": { "slug": "field-notes", "name": "Field Notes" },
"data": {
"email": "ada@example.com",
"subscriberId": "j97f3k2m8n1p4q6r",
"campaignId": "k12a9b8c7d6e5f4g",
"url": "https://acme.com/changelog",
"at": "2026-11-18T09:41:07.000Z"
}
}The request carries these headers:
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | newsletter.sh-webhooks/1 |
Newsletter-Event | The event type, such as email.clicked |
Newsletter-Delivery | A unique id for this delivery. Use it to ignore duplicates. |
Newsletter-Signature | t=1763458867,v1=5f8a… |
email.openedincludes"automatic": truefor Apple Mail automatic opens.email.bouncedincludesbounceType(PermanentorTransient) andbounceSubType.subscriber.*events carry the subscriber's id, email, name, status, tags and source.
Verifying signatures
Every request is signed with your endpoint's secret, so you can be sure it came from newsletter.sh and wasn't altered. The Newsletter-Signature header holds a Unix timestamp t and v1, a hex HMAC-SHA256 of the string {t}.{raw body} keyed with your secret.
import crypto from "node:crypto";
// Verify the Newsletter-Signature header before trusting a webhook.
// rawBody must be the exact bytes you received, before any JSON parsing.
export function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
if (!parts.t || !parts.v1) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${parts.t}.${rawBody}`)
.digest("hex");
// Reject anything older than five minutes to stop replays.
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
return (
fresh &&
expected.length === parts.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
);
}- Compute the signature over the raw request body, not re-serialised JSON.
- Reject old timestamps (five minutes is a good window) to stop replays.
- Answer with any 2xx status quickly, then do slow work in the background.
Retries and auto-disable
A delivery succeeds when your endpoint answers with a 2xx status within 10 seconds. Redirects are not followed. Anything else is retried on this schedule:
That is six attempts over about ten and a half hours, after which the delivery is marked failed. Deliveries can arrive more than once or out of order, so make your handler idempotent using Newsletter-Delivery or the event id.
Testing and the delivery log
- Send test event delivers a
pingevent once, without retries, even to a disabled endpoint. - Each endpoint keeps a log of its last 30 deliveries: event, status code, attempts, timing, error and the exact payload.
- Any delivery can be redelivered with one click.