Webhooks

Test and resend

Send test events, inspect delivery history, and resend webhook deliveries.

Use these endpoints to check that your receiver works, see what Scribeless sent, and send a delivery again.

The same tools are available in the Scribeless app under Settings > Organization > Webhooks.

X-API-Key: YOUR_API_KEY

Send a test event

POST https://platform.scribeless.co/api/webhooks/{webhookId}/test

Sends a sample payload to the subscription URL right away and returns the result. Test events are sent even when the subscription is inactive.

Field	Type	Description
`event_type`	string	Optional. Event type to send. Defaults to the subscription's first event type.

curl --request POST 'https://platform.scribeless.co/api/webhooks/WEBHOOK_SUBSCRIPTION_ID/test' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '{
    "event_type": "recipient.shipped"
  }'

{
  "outcome": {
    "status": "succeeded",
    "responseStatus": 204,
    "error": null
  },
  "delivery": {
    "id": "DELIVERY_ID",
    "subscription_id": "WEBHOOK_SUBSCRIPTION_ID",
    "event_type": "recipient.shipped",
    "event_id": "evt_test_9f86d081884c7d659a2feaa0c55ad015",
    "payload": {},
    "status": "succeeded",
    "is_test": true,
    "attempt_count": 1,
    "last_attempt_at": "2026-01-01T10:00:00.000000+00:00",
    "next_attempt_at": null,
    "response_status": 204,
    "response_body": "",
    "error": null,
    "created_at": "2026-01-01T10:00:00.000000+00:00",
    "updated_at": "2026-01-01T10:00:00.000000+00:00"
  }
}

payload holds the full event body that was sent; it is shortened here.

The recipient.shipped example represents production starting. Sending a test event does not change a real recipient's status or start production. A succeeded result means your webhook endpoint accepted the request; it does not confirm postal-service handoff or delivery to the recipient.

Test events are signed like real events, so you can check your signature verification with them. You can recognise them by:

An event id starting with evt_test_.
The fixed recipient ID 00000000-0000-4000-8000-000000000001.

Test deliveries appear in the delivery history but are never retried.

`outcome.status`	Meaning
`succeeded`	Your endpoint returned a `2xx` status.
`retrying`	The attempt failed and a retry is scheduled.
`failed`	The attempt failed and no retry is scheduled.
`skipped`	The delivery was already being sent or had already succeeded.

List deliveries

GET https://platform.scribeless.co/api/webhooks/{webhookId}/deliveries

Lists deliveries for a subscription, newest first.

Query parameter	Type	Description
`limit`	integer	Optional. Number of deliveries to return, from `1` to `100`. Defaults to `25`.
`status`	string	Optional. `pending`, `delivering`, `succeeded`, or `failed`.
`event_type`	string	Optional. Only return deliveries for this event type.
`starting_after`	string	Optional. ID of the last delivery on the previous page.

curl --request GET 'https://platform.scribeless.co/api/webhooks/WEBHOOK_SUBSCRIPTION_ID/deliveries?status=failed&limit=50' \
  --header 'X-API-Key: YOUR_API_KEY'

{
  "data": [
    {
      "id": "DELIVERY_ID",
      "subscription_id": "WEBHOOK_SUBSCRIPTION_ID",
      "event_type": "recipient.ready",
      "event_id": "evt_5b3c2f8e0e7a4c3f9b1d2a4e6f8a0b1c",
      "payload": {},
      "status": "failed",
      "is_test": false,
      "attempt_count": 8,
      "last_attempt_at": "2026-01-02T14:00:00.000000+00:00",
      "next_attempt_at": null,
      "response_status": 500,
      "response_body": "Internal Server Error",
      "error": "Webhook endpoint returned 500",
      "created_at": "2026-01-01T10:00:00.000000+00:00",
      "updated_at": "2026-01-02T14:00:00.000000+00:00"
    }
  ],
  "has_more": false
}

When has_more is true, request the next page with starting_after set to the id of the last delivery in data.

Field	Description
`status`	`pending` until the delivery is due, `delivering` while an attempt is in flight, then `succeeded` or `failed`. A `pending` delivery with `attempt_count` above `0` is waiting for a retry.
`attempt_count`	Attempts made so far.
`next_attempt_at`	When the next attempt is due, or `null`.
`response_status`, `response_body`, `error`	Result of the latest attempt. `response_body` and `error` are limited to the first 4,000 characters.

Resend a delivery

POST https://platform.scribeless.co/api/webhooks/{webhookId}/deliveries/{deliveryId}/resend

Sends a delivery again right away and returns the result in the same shape as Send a test event. The event id stays the same, so your idempotency handling still applies. Resending a delivery that has used all its retries makes one extra attempt.

curl --request POST 'https://platform.scribeless.co/api/webhooks/WEBHOOK_SUBSCRIPTION_ID/deliveries/DELIVERY_ID/resend' \
  --header 'X-API-Key: YOUR_API_KEY'

Status codes

Status	Meaning
`200`	Request succeeded. Check `outcome.status` for the delivery result.
`400`	Invalid payload or query parameters.
`401`	Missing, malformed, invalid, or unauthorized API key.
`404`	Webhook subscription or delivery not found.
`409`	The delivery is already being sent, or was not found for this subscription.
`500`	Webhook operation failed unexpectedly. Retry or contact support if it persists.

Receive deliveries

Verify, acknowledge, and process Scribeless webhook deliveries.