Webhooks

The SpeechLive webhooks help your application to react to specific changes happening to the dictations of your subscription.

Once you have set up a webhook, SpeechLive will send an HTTP request to the configured URL providing information on the event, whenever the event hook is triggered on your subscription.

Visit our Workflow Administration documentation to learn more about how to manage the webhooks on your subscription.

Security

Our webhooks provide authentication and message security control as security mechanisms. The security methods are offered in two different ways - Shared Secret and Hash-based Message Authentication Code (HMAC).

Shared Secret

Shared Secret is a basic service authentication where the provider and the listener share a common secret. The listener should validate that the value received in the webhook requests matches the expected secret. Only requests with the correct secret should be processed by listeners. In SpeechLive webhooks, this secret is defined during the set up of the webhook and will be included in the "X-Trouble-Secret" header of each request. This key should be kept confidential and never exposed publicly.

HMAC

Hash-based Message Authentication Code is a cryptographic technique that combines a signing key and a hash function to generate a unique signature for a message. This signature can be used to verify the origin and integrity of the data. The signing key of your subscription can be found in the developer area of the workflow administration. This key should be kept confidential and never exposed publicly.

When sending the webhook requests, SpeechLive service will use the signing key to generate a unique hash value of each webhook payload using the HMAC algorithm with the hash function SHA-256. This hash value is then encoded to base64 and included in the "X-Trouble-Request-Hash" header of each request.

When the listener of the webhook receives the request, he should extract the hash value from the header and regenerates a hash using the received payload and its own copy of the signing key. Then the generated hash should be compared with the one received in the webhook header. If the two hashes match, it indicates that the webhook payload has not been altered in transit and that it was indeed sent by SpeechLive service. If the signatures do not match, the receiver should treat the payload as potentially compromised and take appropriate action, such as rejecting the data or investigating the issue.

Generating HMAC hashes

The following examples will help integrators to generate the HMAC hashes and validate the requests:

Payload Content

As mentioned above, SpeechLive webhooks will provide information about the events that have been set up for your subscription. This information is sent as a JSON payload in the body of the request. The payload can be two different types of objects that contain the data about the entity of the event - Dictation or Attachment.

The following is a list of events and their associated payload objects:

The following is a description of the properties of the possible objects and their nested entities:

Timeout and retry

When SpeechLive calls your application, it enforces a default timeout of 100 seconds.

If the call is failed, SpeechLive retries 2 times with a 2 seconds interval.

Responses with a 4xx status code aren't retried.

Limitations

Webhook events will not be triggered by transcriptions added by the Transcription Services.

Webhook events will not be triggered by dictations and attachments created using the legacy SpeechLive Web application (speechexec.com).

Webhook events will not be triggered by SpeechExec desktop applications.