Webhooks

Recipient events

Receive signed webhook events as recipients move through their lifecycle.

Use recipient events when your integration needs to follow recipients as they are created, edited, approved, and enter production, for example to keep a CRM in sync.

Create a subscription first with POST /api/webhooks.

Events

Event	When it fires
`recipient.created`	A recipient was added to a campaign. `recipient.status` carries its initial status.
`recipient.updated`	A recipient's details (name, address, company, email, variables, or campaign) were changed.
`recipient.invalid`	A recipient failed validation and needs fixing before it can be sent.
`recipient.ready`	A recipient was approved and is ready to be sent.
`recipient.shipped`	Production has started and no more edits can be made. This does not confirm postal-service handoff or delivery.
`recipient.ignored`	The recipient was skipped, for example as a duplicate, and will not be sent.

Events fire for every change, whether it was made in the Scribeless app, through the API, or by the Scribeless team.

Status events fire only when the status changes after the recipient is created. A recipient created as ready, for example in a campaign that is already ready, only sends recipient.created.
recipient.updated fires only when a field in the payload changes. Saving without changes, status changes, and HTML body updates do not send it. An edit that also changes the status sends both events.
shipped is the last status with a recipient webhook event. There are currently no separate events for postal-service handoff or delivery to the recipient. We're working on adding these events. Deleting a recipient does not send an event.

Production status and postal handoff

recipient.shipped means production has started and no more edits can be made. It does not confirm that the postal service has received the note or that the note has been delivered. Do not use this event as carrier tracking or proof of delivery.

Postal-service handoff usually happens within 24 hours of production starting. This is a typical operational expectation, not a guarantee.

For example, when you receive recipient.shipped, show “In production” in your CRM or customer updates. The event does not support showing “Handed to the postal service” or “Delivered”.

Payload

This example records a transition from ready to shipped: production has started and edits are locked. The event name, status value, and shipped_at field keep their existing API names.

{
  "id": "evt_5b3c2f8e0e7a4c3f9b1d2a4e6f8a0b1c",
  "type": "recipient.shipped",
  "created_at": "2026-01-01T12:00:00.123456+00:00",
  "team_id": "TEAM_ID",
  "previous_status": "ready",
  "recipient": {
    "id": "RECIPIENT_ID",
    "campaign_id": "CAMPAIGN_ID",
    "status": "shipped",
    "title": null,
    "first_name": "Ada",
    "last_name": "Lovelace",
    "company": "Analytical Engines Ltd",
    "email": "ada@example.com",
    "domain": "example.com",
    "address1": "12 St James's Square",
    "address2": null,
    "address3": null,
    "city": "London",
    "state": null,
    "postal_code": "SW1Y 4JH",
    "country": "GB",
    "region": null,
    "variables": {
      "externalId": "order_12345"
    },
    "created_at": "2025-12-31T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00",
    "shipped_at": "2026-01-01T12:00:00+00:00"
  }
}

Field	Description
`id`	Event ID. Use it as the idempotency key.
`type`	Event type.
`created_at`	When the change happened.
`team_id`	Team that owns the recipient.
`previous_status`	Recipient status before the change. `null` for `recipient.created`.
`recipient`	The recipient at the moment of the change, not when the webhook request reaches your endpoint.
`recipient.status`	Recipient lifecycle status. `shipped` means production has started and edits are locked.
`recipient.shipped_at`	Timestamp recorded when the recipient is marked `shipped` for production. It does not confirm postal-service handoff or delivery to the recipient.

recipient.variables carries the custom fields supplied with the recipient, including externalId for matching records in your system. HTML bodies from HTML recipients are not included.

Fields may be added to the payload over time. Ignore fields your integration does not use.

Ordering

Events for one recipient can arrive out of order, for example when an earlier delivery is retried. Compare created_at, or fetch the recipient when you need its latest state.

Next step

Use Receive deliveries to verify signatures and respond to deliveries.

Manage subscriptions

Create and manage Scribeless webhook subscriptions.

QR scan events

Receive signed webhook events when Smart QR codes are scanned.