Webhooks
Manage subscriptions
Create and manage Scribeless webhook subscriptions.
Use these endpoints to create, list, update, pause, and delete webhook subscriptions.
Webhook management endpoints use the same team API key authentication as the rest of the Scribeless API.
X-API-Key: YOUR_API_KEY
Create a subscription
POST https://platform.scribeless.co/api/webhooks
Content-Type: application/json
X-API-Key: YOUR_API_KEY
| Field | Type | Description |
|---|---|---|
event_type | string | Use qr_code.scanned. |
url | string | Public HTTPS endpoint that should receive webhook deliveries. |
Webhook URLs must use HTTPS and resolve to a public IP address.
curl --request POST 'https://platform.scribeless.co/api/webhooks' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_API_KEY' \
--data '{
"event_type": "qr_code.scanned",
"url": "https://example.com/scribeless/webhooks"
}'
Successful requests return the subscription and its signing secret. Store secret securely when it is returned; Scribeless does not include it in list or update responses.
{
"id": "WEBHOOK_SUBSCRIPTION_ID",
"team_id": "TEAM_ID",
"event_type": "qr_code.scanned",
"url": "https://example.com/scribeless/webhooks",
"status": "active",
"created_at": "2026-01-01T10:00:00.000000+00:00",
"updated_at": "2026-01-01T10:00:00.000000+00:00",
"secret": "whsec_SIGNING_SECRET"
}
List subscriptions
GET https://platform.scribeless.co/api/webhooks
curl --request GET 'https://platform.scribeless.co/api/webhooks' \
--header 'X-API-Key: YOUR_API_KEY'
The response is an array of non-deleted subscriptions.
[
{
"id": "WEBHOOK_SUBSCRIPTION_ID",
"team_id": "TEAM_ID",
"event_type": "qr_code.scanned",
"url": "https://example.com/scribeless/webhooks",
"status": "active",
"created_at": "2026-01-01T10:00:00.000000+00:00",
"updated_at": "2026-01-01T10:00:00.000000+00:00"
}
]
Update a subscription
PATCH https://platform.scribeless.co/api/webhooks/{webhookId}
Use this endpoint to change the delivery URL or switch a subscription between active and inactive.
curl --request PATCH 'https://platform.scribeless.co/api/webhooks/WEBHOOK_SUBSCRIPTION_ID' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_API_KEY' \
--data '{
"status": "inactive"
}'
| Field | Type | Description |
|---|---|---|
url | string | Optional. New public HTTPS endpoint. |
status | string | Optional. active or inactive. |
Send at least one of url or status.
Delete a subscription
DELETE https://platform.scribeless.co/api/webhooks/{webhookId}
curl --request DELETE 'https://platform.scribeless.co/api/webhooks/WEBHOOK_SUBSCRIPTION_ID' \
--header 'X-API-Key: YOUR_API_KEY'
Successful deletes return 204 No Content.
Status codes
| Status | Meaning |
|---|---|
200 | Subscription listed or updated. |
201 | Subscription created. |
204 | Subscription deleted. |
400 | Invalid payload, invalid status, invalid event type, or webhook URL is not an HTTPS public URL. |
401 | Missing, malformed, invalid, or unauthorized API key. |
404 | Webhook subscription not found. |
409 | A non-deleted subscription already exists for the same event type and URL. |
500 | Webhook operation failed unexpectedly. Retry or contact support if it persists. |
Next step
After creating a subscription, use QR scan events to verify and process incoming deliveries.