Notifications (Webhooks)

The Rev API allows you to specify a callback URL to get notifications on the status of a given order. You set it up the moment you place an order through our /orders API by including a Notification element within the JSON body of the request. You can control the number of notifications sent by specifying the level of detail.

We offer two options: FinalOnly, by which you get a single notification the moment your order is in the Completed step and attachments are ready to be downloaded, and Detailed, triggered whenever the order status changes or when comments are added to the order.

We send a POST request to the URL you specify. The request contains data in application/x-www-form-urlencoded encoding. It contains the following:

  • order_number: the order number assigned by Rev
  • client_ref: the client reference number for the order, if any
  • status: the current status of the order within our internal workflow
  • comment: the most recent comment associated with the order, if any

Here’s an example of the body of a request to place a Caption order, and at the same time requesting to be notified once the order is in the Completed state:

  "caption_options": {
    "inputs": [
        "uri": "urn:rev:inputmedia:43939absfziow"
    "output_file_formats": [
    "notification": {
    "url": "",
    "level": "FinalOnly"

Once the order is completed and attachments are ready to be retrieved, we would send a POST request to with data similar to this one:


Keep in mind that we ignore response codes when sending out notifications; we also do not try to resend if the request was unsuccessful.

For a detailed description of retrieving attachments, please visit