Skip to content

Webhook callback

Info

Documents are currently in BETA and the API interface may change when this is deemed necessary.

Once configured during creation it is possible to receive an callback once the document goes through a state change. In order to process the results automatically in your backend.

The following state changes result in the webhook being called:

  • Create
  • Update
  • Delete

Callback URL's

The callback URL has must meet the following conditions, besides being a valid URL in order to be usable for the callback functionality:

  • Must be HTTPS
  • Cannot be localhost or localdomain
  • Cannot be an IP address (IPv4 and/or IPv6)
  • Must be resolvable for the API (eg. no internal/local domains)

Callback message

The Scriptix API will always call the configurated HTTPS endpoint with the following message. It is possible to configure custom headers (eg. an authentication key) but the headers stated below are not overridable.

Callback headers

The following headers are always present

Header Value Description
X-Scriptix-Session ${transcriptSessionId} The Scriptix Transcript Session ID
X-Scriptix-Document ${documentId} The document ID
Content-Type application/json The content type of the callback message

Callback body

The callback body is a JSON body containing an object with the following keys

Key Type Description
sessionId string The Scriptix Transcript Session ID
documentId string The document ID

Automatic retry

The HTTP webhook endpoint on the customer side should always respond with an 2XX status code within 20 seconds or the request will be marked as failed. When this happens an automatic retry will start after a certain period. The following intervals have been configured.

Delay Time after document state change
00:00 Immediate after state change
01:00 1 minute after state change
02:00 3 minutes after state change
05:00 8 minutes after state change
15:00 23 minutes after state change
30:00 53 minutes after state change

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

Example flows

The following flows are examples on how this functionality could be leveraged in order to enhance the capabilities of your own product.

Document creation

sequenceDiagram autoNumber participant Customer participant Editor participant Scriptix API alt Automated API flow opt Transcriptsession Callback Scriptix API->>Customer: Webhook Transcript Session is finished end activate Customer Customer->>Scriptix API: Create document through API activate Scriptix API Note left of Scriptix API: Create document Scriptix API-->>Customer: Document metadata deactivate Scriptix API deactivate Customer else Editor through Scriptix portal Editor->>Scriptix API: Create document through Scriptix portal activate Scriptix API Note left of Scriptix API: Create document Scriptix API-->>Editor: Document metadata deactivate Scriptix API end Scriptix API->>Customer: Webhook callback: DocumentStatusChange activate Customer Customer->>Scriptix API: Retrieve latest version of document activate Scriptix API Scriptix API-->>Customer: Latest document deactivate Scriptix API deactivate Customer

Document can be created by eather the API directly or through our portal in the role of an Editor1. In either case the flow consists of a few steps:

  1. API (Optional) If configured in the TranscriptSession a webhook callback can be made to the customer in order to notify a TranscriptSession is done.
  2. API The customer creates the document through the API.
  3. API The Scriptix API will reply with the metadata of the created document.
  4. Portal The editor creates a document from an existing TranscriptSession through the Scriptix portal.
  5. Portal The Scriptix API creates the document and redirects the customer to the newly created document.
  6. When configured a webhook callback is performed to the provided endpoint with a DocumentStatusChange object.
  7. The customer retrieves the latest version of the document.
  8. The Scriptix API provides the latest version of the document.

Document update

sequenceDiagram autoNumber participant Customer participant Editor participant Scriptix API alt Automated API flow activate Customer Customer->>Scriptix API: Update document through API activate Scriptix API Note left of Scriptix API: Update document Scriptix API-->>Customer: Document metadata deactivate Scriptix API deactivate Customer else Editor through Scriptix portal Editor->>Scriptix API: Update document through Scriptix portal activate Scriptix API Note left of Scriptix API: Update document deactivate Scriptix API end Scriptix API->>Customer: Webhook callback: DocumentStatusChange activate Customer Customer->>Scriptix API: Retrieve latest version of document activate Scriptix API Scriptix API-->>Customer: Latest document deactivate Scriptix API deactivate Customer
  1. API A customer implementation updates the document through the API.
  2. API The Scriptix API will respond with the latest document metadata.
  3. Portal The editor updates the document through the Scriptix Portal.
  4. When configured a webhook callback is performed to the provided endpoint with a DocumentStatusChange object.
  5. The customer retrieves the latest version of the document.
  6. The Scriptix API provides the latest version of the document in the requested format.

Document removal

sequenceDiagram autoNumber participant Customer participant Editor participant Scriptix API alt Automated API flow activate Customer Customer->>Scriptix API: Remove document through API activate Scriptix API Note left of Scriptix API: Remove document Scriptix API-->>Customer: HTTP No Content (204) deactivate Scriptix API deactivate Customer else Editor through Scriptix portal Editor->>Scriptix API: Remove document through Scriptix portal activate Scriptix API Note left of Scriptix API: Remove document deactivate Scriptix API end Scriptix API->>Customer: Webhook callback: DocumentStatusChange activate Customer Customer->>Scriptix API: Retrieve latest version of document activate Scriptix API Scriptix API-->>Customer: HTTP Not Found (404) deactivate Scriptix API deactivate Customer
  1. API A customer implementation removes the document through the API.
  2. API The Scriptix API will respond with an empty HTTP No Content response.
  3. Portal The editor removes the document through the Scriptix Portal and gets redirected to the TranscriptSession page.
  4. When configured a webhook callback is performed to the provided endpoint with a DocumentStatusChange object.
  5. The customer tries to retrieves the latest version of the document.
  6. The Scriptix API responds with a 404 Not Found, indicating that the document is not longer available.

  1. A person whom edits a transcript or caption file through the Scriptix API portal. Or equivalent functionality provided through a third party platform. ↩