Webhooks

A subscriber left

Posted to the subscriptions to subscriber.unsubscribed when a subscriber leaves: the unsubscribe link of an email, the API or MCP, or the app. A bounce or a complaint does not produce it; the same person can be reported more than once — handle it as idempotent. Signed and retried like every event. The test event (POST /api/v1/webhooks/{id}/test) arrives under this type too, with data: { test: true, message } and none of the fields of the real event: check data.test first.

postWebhooksubscriber.unsubscribed

Headers

Mailcheer-Signaturestring required

t=<unix timestamp>,v1=<hex>: v1 is the HMAC-SHA256 of "<t>.<raw body>" keyed with the subscription's secret. Reject a t more than 300 seconds away from your clock.

Mailcheer-Timestampstring required

The same t, in seconds.

Mailcheer-Event-Idstring required

The event's id — the same on every attempt and every replay: the deduplication key.

Mailcheer-Event-Typestring required

The event's type.

Mailcheer-Delivery-Idstring required

This delivery. A manual replay gets a new one.

Mailcheer-Attemptstring required

The attempt number, starting at 1.

Payload

OR

Example payload

{
  "id": "evt_Kq1wE2rT3yU4iO5p",
  "type": "subscriber.unsubscribed",
  "created_at": "2026-09-25T12:41:58.866Z",
  "data": {
    "subscriber_id": "cmu5x0p3r00041n7n8m2t6hij",
    "email": "claire@example.com",
    "status": "unsubscribed",
    "reason": "unsubscribe",
    "campaign_id": "cmu79z1ab00001n7nqk2d4efg",
    "message_id": "cmu7a2k9q000b1n7n3v5c8xyz"
  }
}

Response

Any 2xx within 15 seconds acknowledges receipt. Anything else — another status, a redirect (not followed), no answer, a network error — is retried: 5 attempts in all, the next ones 30 s, 2 min, 10 min and 1 h after the previous failure.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.