DocsIntegrations

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

  1. Open the settings
    An owner goes to Settings → Webhooks and adds an endpoint URL. It must be https:// and publicly reachable; private and internal addresses are refused.
  2. Pick events
    Choose which events this endpoint receives. A newsletter can have up to 10 endpoints.
  3. Save the signing secret
    A secret starting with whsec_ is shown once. You can reveal it again later from the endpoint. Use it to verify signatures.
  4. Send a test
    Send test event delivers a ping event, so you can check your handler before real events arrive.

Events

Webhook events
EventSent when
subscriber.createdA new address joined the list, with any status.
subscriber.subscribedAn address became subscribed: signup, confirmation, import or API.
subscriber.unsubscribedAn address unsubscribed or was unsubscribed.
email.deliveredA campaign email reached the recipient's mail server.
email.openedA campaign email was opened (indicative; automatic opens are flagged).
email.clickedA tracked link was clicked. Includes the URL.
email.bouncedA campaign email bounced. Includes the bounce type.
email.complainedA recipient marked a campaign email as spam.
campaign.sentA campaign finished sending.
poll.votedA reader voted in a poll, or changed their vote.
import.completedA 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.

email.clickedJSON
{
  "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:

Webhook request headers
HeaderValue
Content-Typeapplication/json
User-Agentnewsletter.sh-webhooks/1
Newsletter-EventThe event type, such as email.clicked
Newsletter-DeliveryA unique id for this delivery. Use it to ignore duplicates.
Newsletter-Signaturet=1763458867,v1=5f8a…
  • email.opened includes "automatic": true for Apple Mail automatic opens.
  • email.bounced includes bounceType (Permanent or Transient) and bounceSubType.
  • 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.

verify.jsJavaScript
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:

Attempt 1+1 min+5 min+30 min+2 h+8 h

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 ping event 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.
newsletter.sh

Newsletters on your own sending account. Invite-only, sent through Amazon SES or the provider you already use.

© 2026 newsletter.sh