Notifications (Webhooks)

If a callback URL is specified in the order request submitted to POST /orders APIs (Transcription, Caption, AI Transcription, or AI Caption), then notifications will be sent to the provided URL when the state of the order changes. Currently, we support notifications for Transcription and Caption orders. The Level parameter in the order_request controls when notifications are sent. The possible values are:

Level parameter value Notification Trigger
FinalOnly When the order is in the Completed status and attachments are available to download.
FileComplete When an individual file has been completed and the related attachment is ready to download.
Detailed When the order status changes (such as going from being transcribed to in review), comments are added to the order, or when an individual file has been completed.
Additionally, the "content_type" parameter allows for different content-type payloads to be sent to the Notification Url:
  • FormUrlEncoded - application/x-www-form-urlencoded (default)
  • ApplicationJson - application/json

The update is sent by making a POST request to the specified URL. The post contains data in the designated content-type format (application/x-www-form-urlencoded by default) with the following parameters:

Name Description
order_number The Rev-assigned number of the order.
client_ref The client reference number for the order, if any.
type The type of notification.
status The current status of the order.
comment The most recent comment associated with the update, if any.
deliverable_type The type of the delivered file. This only surfaces when a file has been completed and the Level value is set to FileComplete or Detailed.
attachment_id The id of the downloadable attachment for a delivered file. This only surfaces when a file has been completed and the Level value is set to FileComplete or Detailed.

type
The following are a list of possible notification type values that could be received per notification:

  • status_update - This notification type is received when the status of the order changes. This can be from a status change on the order (such as going from being transcribed to in review) or from a comment being added to the order.
  • file_completed - This notification type is received when an individual file from the order has been completed.
  • order_completed - This notification type is received when the entire order has been completed.


deliverable_type
The following are a list of possible deliverable type values based on what was ordered:

  • transcript - Human transcripts for transcription orders
  • instant_first_draft - Instant first draft AI transcripts for transcription orders
  • ai_transcript - AI transcripts for AI transcription orders
  • legal_ready_to_certify - Legal Ready To Certify transcripts for legal transcription orders
  • legal_human_rough_draft - Legal Human Rough Draft transcripts for legal transcription orders
  • legal_ai_rough_draft - Legal AI Rough Draft transcripts for legal transcription orders
  • caption - Human captions for caption orders
  • subtitle - Foreign language subtitles for caption orders
  • ai_caption - AI captions for AI caption orders

The sandbox environment will provide the following deliverable types:

  • sandbox_transcript - Sandbox transcript for sandbox transcription orders
  • sandbox_caption - Sandbox captions for sandbox caption orders


An example submission looks like this: 

order_number=TC2012345&client_ref=my+recording&type=order_completed&status=Delivered

Currently, the notification is sent and the status code returned is inspected. If the notification failed to send, the request is resent in 30-minute intervals for 24 hours.