Skip to main content

Basic Callback

Info​

⚠️ Looking for advanced webhook management features?

This page covers basic one-off document callbacks. For custom webhook endpoints per organization, delivery logs, security, and event-type configuration, see the Organization Webhooks Guide.

Documents are currently in BETA, and the API interface may change when necessary.

Once configured during creation, it is possible to receive a callback when a document goes through a state change. This allows your backend to process the results automatically.

State Changes That Trigger a Callback​

  • Create
  • Update
  • Delete

Callback URLs​

The callback URL must meet the following conditions (in addition to being a valid URL):

  • Must use HTTPS
  • Cannot be localhost or localdomain
  • Cannot be an IP address (IPv4 or IPv6)
  • Must be resolvable by the Scriptix API (i.e., no internal or local domains)

Callback Message​

The Scriptix API will always call the configured HTTPS endpoint with a message. You can configure custom headers (e.g., authentication), but the headers listed below cannot be overridden.

Callback Headers​

HeaderValueDescription
X-Scriptix-Session${transcriptSessionId}The Scriptix Transcript Session ID
X-Scriptix-Document${documentId}The document ID
Content-Typeapplication/jsonThe content type of the message

Callback Body​

The callback body is a JSON object with the following keys:

KeyTypeDescription
sessionIdstringThe Scriptix Transcript Session ID
documentIdstringThe document ID

Automatic Retry​

The HTTP webhook endpoint on the customer side should always respond with a 2XX status code within 20 seconds, or the request will be marked as failed. When this happens, an automatic retry will be triggered after a set interval.

Retry Intervals​

DelayTime After Document State Change
00:00Immediately after state change
01:001 minute after state change
02:003 minutes after state change
05:008 minutes after state change
15:0023 minutes after state change
30:0053 minutes after state change

If a callback could not be performed successfully after the final delay, the callback is abandoned, and no further notification is sent about the state change.

Example Flows​

The following flows show how this functionality can be leveraged in your implementation.

📄 Document Creation​

Steps​

  1. (Optional, API only) If configured in the TranscriptSession, a webhook callback notifies the customer that the session has finished.
  2. API: The customer creates the document via the API and receives metadata.
  3. Portal: An editor creates a document from an existing TranscriptSession via the Scriptix Portal; the API returns metadata.
  4. Callback: A DocumentStatusChange webhook callback is sent (if configured).
  5. The customer retrieves the latest version of the document.
  6. The Scriptix API returns the final document data.

Document Update​

Steps​

  1. API: The customer updates the document via the API and receives updated metadata.
  2. Portal: An editor updates the document through the Scriptix Portal.
  3. Callback: A DocumentStatusChange webhook callback is sent (if configured).
  4. The customer retrieves the latest version of the document.
  5. The Scriptix API returns the latest document data.

Document Deletion​

Steps​

  1. API: The customer removes the document via the API and receives a 204 No Content response.
  2. Portal: An editor removes the document through the Scriptix Portal and is redirected to the TranscriptSession page.
  3. Callback: A DocumentStatusChange webhook callback is sent (if configured).
  4. The customer tries to retrieve the latest version of the document.
  5. The Scriptix API responds with 404 Not Found, indicating the document is no longer available.

Editor refers to a person who edits a transcript or caption file through the Scriptix Portal, or equivalent functionality provided through a third-party platform.

🔗 Related Docs​