Letterby Docs

Webhooks

Receive events from Letterby, verify their signature and handle retries.

A webhook sends an HTTPS POST to your server when something happens: a subscriber is verified, an agreement starts or ends, a payout is sent.

Events go to the team that promotes offers (the creator side).

Set up

Create an endpoint with the events you want.

curl -X POST https://api.letterby.com/v1/webhooks \
  -H "Authorization: Bearer $LETTERBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/letterby",
    "enabled_events": ["subscriber.verified", "payout.paid"]
  }'

Store the signing_secret from the response. It is returned only once.

Verify the signature of each delivery, then answer with any 2xx status within 10 seconds.

The URL must use https and a public host. See Create a webhook endpoint for all fields.

Events

EventSent when
subscriber.verifiedA subscriber passed screening and you earned the payout.
subscriber.reversedA subscriber unsubscribed during screening and no longer counts.
agreement.acceptedAn agreement became active, at once or after the advertiser approved it.
agreement.endedAn agreement ended, by you or by the advertiser.
payout.paidA payout was sent to your Stripe account.
payout.failedA payout transfer failed.

Delivery format

POST /webhooks/letterby HTTP/1.1
Content-Type: application/json
User-Agent: Letterby-Webhooks/1.0
Letterby-Event-Type: subscriber.verified
Letterby-Event-Id: conv.019a8a52-6f3e-7c1a-9d52-3b1f6f0c2a11.verified
Letterby-Signature: v1,t=1794571200,h=Xk3โ€ฆ

{
  "id": "conv.019a8a52-6f3e-7c1a-9d52-3b1f6f0c2a11.verified",
  "type": "subscriber.verified",
  "created_at": "2026-11-15T10:00:00.000Z",
  "data": { }
}
FieldMeaning
idThe event id. It stays the same across retries. Use it to ignore duplicates.
typeThe event name.
created_atWhen this delivery attempt was sent.
dataThe event payload, described below.

Payloads

subscriber.verified

FieldTypeMeaning
conversion_idstringThe verified conversion.
agreement_idstringThe agreement that brought the subscriber.
offer_idstringThe offer.
creator_amount_centsintegerWhat you earned.
platform_fee_centsintegerLetterby's fee on this conversion.
currencystringusd.
countrystring or nullThe subscriber's country code.

subscriber.reversed

FieldTypeMeaning
pending_subscriber_idstringThe subscriber record.
agreement_idstringThe agreement.
offer_idstringThe offer.
reasonstringunsubscribed_in_screening_window.

agreement.accepted

FieldTypeMeaning
agreement_idstringThe agreement.
offer_idstringThe offer.
recommender_publication_idstringYour publication.
accepted_payout_centsintegerThe advertiser's payout per subscriber, locked at acceptance.
accepted_currencystringusd.
tracking_slugstringThe slug of your tracking link.
creator_payout_centsintegerYour share per subscriber.
tracking_urlstringThe link to put in your newsletter.

agreement.ended

FieldTypeMeaning
agreement_idstringThe agreement.
publication_idstringYour publication.
ended_atstringWhen it ended.
reasonstring, optionaloffer_archived when the advertiser archived the offer.

payout.paid

FieldTypeMeaning
payout_idstringThe payout.
period_start, period_endstringThe earning period.
amount_centsintegerThe amount sent, after deductions.
deduction_centsintegerTaken out for subscribers reversed after an earlier payout. Usually 0.
currencystringusd.
stripe_transfer_idstringThe Stripe transfer.
line_itemsarrayOne entry per agreement: offer_id, agreement_id, conversions_count, amount_cents.

payout.failed

FieldTypeMeaning
payout_idstringThe payout.
stripe_transfer_idstringThe Stripe transfer.
amount_centsintegerThe amount.
currencystringusd.
reasonstringWhy the transfer failed.
retry_countintegerRetries so far.
max_retriesintegerRetries Letterby will make. 0 means it will not retry.

Verify the signature

Every delivery is signed with your endpoint's signing_secret.

Letterby-Signature: v1,t=<unix seconds>,h=<signature>

The signature is HMAC-SHA256 of <t>.<raw body>, keyed with the full secret string including whsec_, encoded as base64url without padding.

Use the raw request body, exactly as received. Parsing and re-serialising the JSON changes the bytes and breaks the check.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyLetterby(
  rawBody,
  header,
  secret,
  toleranceSeconds = 300,
) {
  const parts = Object.fromEntries(
    header
      .split(",")
      .slice(1)
      .map((p) => [p.slice(0, p.indexOf("=")), p.slice(p.indexOf("=") + 1)]),
  );
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!parts.t || !parts.h || !(age <= toleranceSeconds)) return false;

  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("base64url");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.h);
  return a.length === b.length && timingSafeEqual(a, b);
}

With Express, read the raw body for this route:

app.post(
  "/webhooks/letterby",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ok = verifyLetterby(
      req.body.toString("utf8"),
      req.get("Letterby-Signature") ?? "",
      process.env.LETTERBY_WEBHOOK_SECRET,
    );
    if (!ok) return res.sendStatus(400);

    const event = JSON.parse(req.body);
    // Queue the work, then answer fast.
    res.sendStatus(200);
  },
);

Reject a delivery whose timestamp is more than 5 minutes old. That stops a captured request from being replayed later.

Retries

A delivery fails when your server does not answer 2xx within 10 seconds. Redirects are not followed.

AttemptSent
1Within about a minute of the event
2About 30 seconds later
3About 2 minutes later
4About 10 minutes later
5About 30 minutes later
6About 1 hour later

After 6 failed attempts the delivery is dropped.

After 10 deliveries in a row are dropped, Letterby disables the endpoint and stops sending to it. Turn it back on with Update a webhook endpoint and "disabled": false.

Checklist

  • Verify the signature before trusting a delivery.
  • Answer 2xx quickly and do slow work in a background job.
  • Ignore an id you have already processed. The same event can arrive more than once.
  • Do not rely on order. Events can arrive out of sequence.
  • To rotate a secret, create a new endpoint, switch over, then delete the old one.

On this page