Webhooks

Webhooks provide a powerful mechanism to receive real-time notifications about the status of your asynchronous FFmpeg Commands. Instead of polling for the status of a command, you can provide a webhook URL, and the Fetchmedia system will send a POST request to that URL upon completion of the command.

Endpoints that Support Webhooks

Currently, the primary endpoint that supports webhooks is the Command creation endpoint:

• POST /v1/commands: When creating a command, you can include a webhook parameter in your request body. This parameter should contain the URL where you want to receive the webhook notification.

{
  "input_files": {
    "in_1": "https://example.com/video.mp4"
  },
  "output_files": {
    "out_1": "output.mp4"
  },
  "ffmpeg_commands": ["-i in_1 out_1"],
  "webhook": "https://your-application.com/webhook-receiver"
}

The Webhook Request

When your command has finished processing (either successfully or with an error), the system will send an HTTP POST request to the webhook URL you provided.

Request Details

• Method: POST

• Content-Type: application/json

Payload

The payload of the webhook request is a JSON array containing the details of the output files generated by the command. Each element in the array represents an Asset object with its attributes.

Here is an example of the JSON payload you might receive:

[
  {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "name": "output.mp4",
    "status": "success",
    "download_url": "https://api.fetchmedia.io/v1/files/a1b2c3d4-e5f6-7890-1234-567890abcdef/file.mp4",
    "error": null,
    "ffprobe": null,
    "ffprobe_error": null
  }
]

This payload gives you immediate access to the identifiers and metadata of the files that were created, allowing your application to proceed with follow-up processing, such as downloading the files or updating its own records. If the command fails, the webhook will still be sent, but the payload may be different, reflecting the error state.