Webhooks

📌 Introduction

The webhook feature lets you register a URL that Dailymotion will POSTto whenever a specific event occurs on your accont.

When an event is triggered, for example when a video finishes encoding, Dailymotion:

• Creates an event object containing the event type and its associated data.
• Sends a HTTP POST request with that payload to the URL you specified.

🛠️ Configuring webhooks

📘

Organization accounts

Webhooks can only be set up by Owners. Admins and editors do not have permissions.

🚧

HTTPS required

Your callback URL must use HTTPS. HTTP URLs are rejected.

Webhooks in API v2 are configured as a nested webhook object on the Profile resource. There are no dedicated webhook endpoints: all webhook operations (create, update, read, delete) go through the Profile API.

Authentication: Bearer token with the profile.manage scope. The caller must have an Owner role on the profile.

Create or update a webhook

PATCH /v2/profiles/<profile_id>
Authorization: Bearer <token>
Content-Type: application/json

{
  "webhook": {
    "callback_url":"https://example.com/webhook/dailymotion",
    "events": ["video.created", "video.format.ready"]
  }
}

• callback_url must be a valid HTTPS URL (HTTP not allowed).
• events array must contain at least one valid event type.
• When creating a webhook for the first time, both callback_url and events are required and must be non-null.
• Partial updates: Updating only events or callback_url is supported, but only if a complete webhook already exists on the profile.

Get the webhook configuration

📘

Permissions required

Any user with access to the profile (owner, admin, editor).

Request example:

GET /v2/profiles/<profile_id>?fields=webhook

Response example:

{
  "webhook": {
    "callback_url": "https://example.com/webhook/dailymotion",
    "events": ["video.created", "video.format.ready"]
  }
}

Remove a webhook

PATCH /v2/profiles/<profile_id>
Content-Type: application/json

{
  "webhook": {
    "callback_url": null,
    "events": null
  }
}

Subscribable events

An up-to-date list of events is available in the API error message.

Receiving a webhook

Dailymotion delivers webhooks as standard HTTP POST request with a JSON body. All events share the same structure:

• type: The type of the event (ie. video.created)
• timestamp: A Unix timestamp with milliseconds precision (x1000)
• data: JSON object with additional parameters related to the event

Examples:

{
   "type":"video.created",
   "timestamp":1459863728000,
   "data":{
      "owner_id":"xzy",
      "video_id":"xid"
   }
}

{
   "type":"video.format.processing",
   "timestamp":1459863865000,
   "data":{
      "owner_id":"xyz",
      "video_id":"xid",
      "preset_name":"mp4_h264_aac_hd",
      "status":"processing",
      "progress":52
   }
}

{
   "type":"video.format.ready",
   "timestamp":1459864182000,
   "data":{
      "owner_id":"xyz",
      "video_id":"xid",
      "preset_name":"mp4_h264_aac_hd",
      "status":"ready"
   }
}

{
   "type":"video.published",
   "timestamp":1459863879000,
   "data":{
      "owner_id":"xyz",
      "video_id":"xid"
   }
}

{
   "type":"video.deleted",
   "timestamp":1459864364000,
   "data":{
      "owner_id":"xyz",
      "video_id":"xid"
   }
}

Verifying webhook requests

Every webhook request from Dailymotion API v2 includes a X-DM-Signature header. This allows you to verify that the request genuinely originates from Dailymotion and has not been tampered with. Always validate this header before processing the payload.

Troubleshooting

We recommend using RequestBin to troubleshoot webhooks and inspect payloads during development.

Dailymotion webhook IPs

If you have IP restrictions in place, make sure to authorize the following Dailymotion webhook IPs on your server:

• 3.254.17.195
• 63.33.129.201
• 18.202.188.16

Errors

INVALID_FORMAT

Invalid callback URL: Returned when the provided callback_url uses HTTP instead of HTTPS.

{
  "error": {
    "code": "INVALID_FORMAT",
    "message": "Webhook callback_url must use HTTPS protocol",
    "details": {
      "field": "webhook.callback_url",
    "provided": "http://example.com/webhook",
    "requirement": "HTTPS URL required for security"
  }
}

INVALID_ENUM_VALUE

Invalid event type: Returned when one or more values in the events array are not recognized.

{
  "error": {
    "code": "INVALID_ENUM_VALUE",
    "message": "Invalid webhook event type",
    "details": {
      "field": "webhook.events",
    "invalid_values": ["video.uploaded"],
    "allowed_values": [
      "video.created",
      "video.deleted",
      "video.format.ready",
      "video.format.error",
      "video.format.deleted",
    ]
  }
}