Webhooks — tinysend developers

Webhooks let you receive HTTP POST requests when events happen in tinysend. Use them to sync data, trigger automations, or power AI agents.

Setup

1. POST /webhooks with a URL and list of events
2. tinysend sends a test event to verify your endpoint
3. save the secret from the response — it’s shown only once

curl -X POST https://api.tinysend.com/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhook", "events": ["post.sent", "subscriber.created"]}'

Events

Events use entity.action naming. 30 events across 6 entities.

post

A post is a content piece broadcast to a newsletter’s subscribers.

event	when
post.created	draft created (UI, email, or API)
post.updated	content or settings changed
post.sent	user/agent triggered sending
post.delivered	all emails for this post resolved
post.paused	broadcast paused mid-send
post.resumed	broadcast resumed after pause
post.cancelled	broadcast cancelled
post.viewed	someone viewed the post on the archive website
post.liked	someone reacted to the post

post.sent fires at the moment of approval, not when batches finish submitting. post.delivered fires when every recipient has a terminal status (delivered + bounced + failed = total).

email

An email is any message in the system — inbound or outbound, broadcast or direct.

event	when
email.received	inbound email arrived in a mailbox
email.sent	outbound email submitted to provider
email.delivered	provider confirmed inbox delivery
email.bounced	hard or soft bounce
email.opened	tracking pixel fired
email.clicked	tracked link clicked
email.complained	recipient filed spam complaint
email.replied	recipient replied to an email

subscriber

A person in a specific newsletter.

event	when
subscriber.created	added to a newsletter (form, API, import, or agent)
subscriber.confirmed	double opt-in confirmed
subscriber.unsubscribed	unsubscribed via link, API, or manually
subscriber.deleted	removed from a newsletter

contact

A person across all newsletters in your account.

event	when
contact.created	new contact
contact.updated	contact data changed
contact.deleted	contact removed

list

The audience container — a newsletter, waitlist, or announcement (the event names keep the list.* prefix).

event	when
list.created	new newsletter created
list.updated	settings changed
list.deleted	newsletter removed

mailbox

An addressable email endpoint.

event	when
mailbox.created	new mailbox created
mailbox.updated	settings changed
mailbox.deleted	mailbox removed

Payload

Every webhook delivery uses this envelope:

{
  "id": "01jx...",
  "type": "post.sent",
  "created_at": "2025-06-09T12:00:00Z",
  "data": {
    "post_id": "01jx...",
    "list_id": "01jx...",
    "subject": "Weekly update"
  }
}

Verifying signatures

Each delivery includes an HMAC-SHA256 signature in the X-Tinysend-Signature header, computed with the secret returned at subscription creation.

const crypto = require('crypto');

function verify(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Headers

header	description
X-Tinysend-Event	event type (e.g. post.sent)
X-Tinysend-Signature	HMAC-SHA256 hex signature
X-Tinysend-Delivery-Id	unique delivery ID for idempotency

Delivery

• timeout: 10 seconds
• retries: 3 attempts with backoff
• auto-disable: after 10 consecutive failures
• your endpoint must return 2xx to acknowledge

Managing webhooks

method	endpoint	description
POST	/webhooks	create subscription
GET	/webhooks	list subscriptions
GET	/webhooks/:id	get subscription details
PATCH	/webhooks/:id	update URL, events, or status
DELETE	/webhooks/:id	delete subscription
POST	/webhooks/:id/test	send test event
GET	/webhooks/:id/deliveries	list recent deliveries