Webhooks
Webhook callbacks for document state changes. Webhooks are triggered when documents are created, updated, or deleted.
Document State Changes
Webhooks are triggered on the following document state changes:
- Create - When a document is created
- Update - When a document is updated
- Delete - When a document is deleted
Callback URL Requirements
Callback URLs must meet the following conditions:
- Must be HTTPS
- Cannot be localhost or localdomain
- Cannot be an IP address (IPv4 or IPv6)
- Must be resolvable for the API (no internal/local domains)
Webhook Callback
When a document state change occurs, the API will send a POST request to the configured webhook URL.
Callback Headers
The following headers are always present in webhook callbacks:
| Header | Description |
|---|---|
X-Scriptix-Session | The Scriptix Transcript Session ID |
X-Scriptix-Document | The document ID |
Content-Type | application/json |
Custom headers can be configured, but the headers above are not overridable.
Callback Body
The callback body is a JSON object:
{
"sessionId": "string",
"documentId": "string"
}
| Field | Type | Description |
|---|---|---|
sessionId | string | The Scriptix Transcript Session ID |
documentId | string | The document ID |
Automatic Retry
The webhook endpoint must respond with a 2XX status code within 20 seconds or the request will be marked as failed. Failed requests trigger automatic retries at the following intervals:
| Delay | Time After State Change |
|---|---|
| 00:00 | Immediate |
| 01:00 | 1 minute |
| 02:00 | 3 minutes |
| 05:00 | 8 minutes |
| 15:00 | 23 minutes |
| 30:00 | 53 minutes |
If a callback fails after the final retry (53 minutes), the callback is abandoned and no further notifications are sent.
Webhook Management
List Webhooks
GET /api/v3/admin/customer/{customer_id}/webhooks
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
limit | number | Maximum number of results to return |
offset | number | Number of results to skip |
q | string | Search query |
Get Webhook
GET /api/v3/admin/customer/{customer_id}/webhooks/{webhook_id}
Response:
{
"count": 1,
"total_result": 1,
"result": {
"id": 123,
"type": "string",
"webhook_url": "https://example.com/webhook",
"webhook_method": "POST",
"webhook_headers": ["Authorization: Bearer token"],
"organization_id": 456,
"created_at": "2026-01-15T10:00:00Z",
"last_modified": "2026-01-15T10:00:00Z"
}
}
Create Webhook
POST /api/v3/admin/customer/{customer_id}/webhooks
Request Body:
{
"type": "string",
"webhook_url": "https://example.com/webhook",
"webhook_method": "POST",
"webhook_headers": ["Authorization: Bearer token"],
"organization_id": "456"
}
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Webhook type |
webhook_url | string | Yes | HTTPS URL for webhook callbacks |
webhook_method | string | Yes | HTTP method (e.g., POST) |
webhook_headers | string[] | Yes | Custom headers to include |
organization_id | string | No | Organization identifier |
Update Webhook
PUT /api/v3/admin/customer/{customer_id}/webhooks/{webhook_id}
Request Body: Same as Create Webhook
Delete Webhook
DELETE /api/v3/admin/customer/{customer_id}/webhooks/{webhook_id}
Webhook Configuration in Document Upload
The webhook_url field can be included when uploading documents. The webhook URL is stored as part of document settings and will be used for callbacks related to that document.
Notes
- Webhooks require admin (SYSOP) access to configure via the back-office interface
- Custom headers can be configured for authentication purposes
- Webhook callbacks are performed for document state changes only
- The webhook endpoint must be publicly accessible and respond quickly (within 20 seconds)