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
| Event | Sent when |
|---|---|
subscriber.verified | A subscriber passed screening and you earned the payout. |
subscriber.reversed | A subscriber unsubscribed during screening and no longer counts. |
agreement.accepted | An agreement became active, at once or after the advertiser approved it. |
agreement.ended | An agreement ended, by you or by the advertiser. |
payout.paid | A payout was sent to your Stripe account. |
payout.failed | A 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": { }
}| Field | Meaning |
|---|---|
id | The event id. It stays the same across retries. Use it to ignore duplicates. |
type | The event name. |
created_at | When this delivery attempt was sent. |
data | The event payload, described below. |
Payloads
subscriber.verified
| Field | Type | Meaning |
|---|---|---|
conversion_id | string | The verified conversion. |
agreement_id | string | The agreement that brought the subscriber. |
offer_id | string | The offer. |
creator_amount_cents | integer | What you earned. |
platform_fee_cents | integer | Letterby's fee on this conversion. |
currency | string | usd. |
country | string or null | The subscriber's country code. |
subscriber.reversed
| Field | Type | Meaning |
|---|---|---|
pending_subscriber_id | string | The subscriber record. |
agreement_id | string | The agreement. |
offer_id | string | The offer. |
reason | string | unsubscribed_in_screening_window. |
agreement.accepted
| Field | Type | Meaning |
|---|---|---|
agreement_id | string | The agreement. |
offer_id | string | The offer. |
recommender_publication_id | string | Your publication. |
accepted_payout_cents | integer | The advertiser's payout per subscriber, locked at acceptance. |
accepted_currency | string | usd. |
tracking_slug | string | The slug of your tracking link. |
creator_payout_cents | integer | Your share per subscriber. |
tracking_url | string | The link to put in your newsletter. |
agreement.ended
| Field | Type | Meaning |
|---|---|---|
agreement_id | string | The agreement. |
publication_id | string | Your publication. |
ended_at | string | When it ended. |
reason | string, optional | offer_archived when the advertiser archived the offer. |
payout.paid
| Field | Type | Meaning |
|---|---|---|
payout_id | string | The payout. |
period_start, period_end | string | The earning period. |
amount_cents | integer | The amount sent, after deductions. |
deduction_cents | integer | Taken out for subscribers reversed after an earlier payout. Usually 0. |
currency | string | usd. |
stripe_transfer_id | string | The Stripe transfer. |
line_items | array | One entry per agreement: offer_id, agreement_id, conversions_count, amount_cents. |
payout.failed
| Field | Type | Meaning |
|---|---|---|
payout_id | string | The payout. |
stripe_transfer_id | string | The Stripe transfer. |
amount_cents | integer | The amount. |
currency | string | usd. |
reason | string | Why the transfer failed. |
retry_count | integer | Retries so far. |
max_retries | integer | Retries 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.
| Attempt | Sent |
|---|---|
| 1 | Within about a minute of the event |
| 2 | About 30 seconds later |
| 3 | About 2 minutes later |
| 4 | About 10 minutes later |
| 5 | About 30 minutes later |
| 6 | About 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
2xxquickly and do slow work in a background job. - Ignore an
idyou 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.