Webhooks

A tool to notify your service when videos successfully finish processing and are ready to stream.

A few things to note:

  • At this time, webhooks will only be sent after the processing of a video is complete, and the body will indicate whether the processing of the video succeeded or failed.
  • Only one webhook subscription is allowed per-account.

Subscriptions

Create or Modify the Webhook Subscription

To subscribe to receive webhook notifications on your service, or modify an existing subscription, you will need your Cloudflare API key and your email address.

curl -X PUT --header 'X-Auth-Key:{API-KEY}' --header 'X-Auth-Email:{EMAIL}' 
https://api.cloudflare.com/client/v4/accounts/{account_id}/media/webhook
--data '{"notification_url":"{WEBHOOK-NOTIFICATION-URL"}'

The {WEBHOOK-NOTIFICATION-URL} must include the protocol. Only http:// or https:// is supported.

Example Response to Create or Modify the Webhook Subscription

{
  "result": {
    "notification_url": "http://www.your-service-webhook-handler.com",
    "modified": "2019-01-01T01:02:21.076571Z"
  },
  "success": true,
  "errors": [],
  "messages": []
}

If a subscription is created, the modified timestamp will equal “0001-01-01T00:00:00.0000000Z”

Get the Webhook Subscription

To view a webhook subscription associated with your account:

curl --header 'X-Auth-Key:{API-KEY}' --header 'X-Auth-Email:{EMAIL}' 
https://api.cloudflare.com/client/v4/accounts/{account_id}/media/webhook

Example Response to Get the Webhook Subscription

{ 
  "result": {
    "notification_url": "http://www.your-service-webhook-handler.com",
    "modified": "0001-01-01T00:00:00.0000000Z",
  }
  "success": true,
  "errors": [],
  "messages": []
}

Delete the Webhook Subscription

To delete a webhook subscription associated with your account:

curl -X DELETE --header 'X-Auth-Key:{API-KEY}' --header 'X-Auth-Email:{EMAIL}' 
https://api.cloudflare.com/client/v4/accounts/{account_id}/media/webhook

If there is an entry in errors response field, the webhook has not been deleted, and the request should be re-tried.

Example Response to Delete the Webhook Subscription

{
  "result": "deleted",
  "success": true,
  "errors": [],
  "messages": []
}

Notifications

When a video on your account finishes processing, you will receive a POST request notification with information about the video.

Note the status field indicates whether the video processing finished successfully.

Example POST request body sent in response to successful encoding

{
    "uid": "dd5d531a12de0c724bd1275a3b2bc9c6",
    "thumbnail": "https://cloudflarestream.com/dd5d531a12de0c724bd1275a3b2bc9c6/thumbnails/thumb.png",
    "readyToStream": true,
    "status": {
      "state": "ready"
    },
    "meta": {},
    "labels": [],
    "created": "2019-01-01T01:00:00.474936Z",
    "modified": "2019-01-01T01:02:21.076571Z",
    "size": 62335189,
    "preview": "https://watch.cloudflarestream.com/dd5d531a12de0c724bd1275a3b2bc9c6"
  }

Example POST request body sent in response to failed encoding.

{
    "uid": "dd5d531a12de0c724bd1275a3b2bc9c6",
    "thumbnail": "https://cloudflarestream.com/dd5d531a12de0c724bd1275a3b2bc9c6/thumbnails/thumb.png",
    "readyToStream": false,
    "status": {
      "state": "error"
    },
    "meta": {},
    "labels": [],
    "created": "2019-01-01T01:00:00.474936Z",
    "modified": "2019-01-01T01:02:21.076571Z",
    "size": 62335189,
    "preview": "https://watch.cloudflarestream.com/dd5d531a12de0c724bd1275a3b2bc9c6"
  }