Compressor APIAsync WorkflowsWebhooks

Webhooks

Webhooks allow your application to receive compression results automatically as soon as a job finishes, without keeping an HTTP request open or relying on polling. This is the recommended mechanism for handling long-running or resource-intensive operations such as large videos, archives, and batch jobs.

Enabling Webhooks

To enable webhook delivery, include a webhook object in your request payload:

{
  "webhook": {
    "url": "https://example.com/webhooks/compressor"
  }
}

Providing a webhook URL forces asynchronous processing, regardless of file size or format. The API will immediately acknowledge the request with a job ID, and processing will continue in the background.

Webhook Delivery

Once processing completes — successfully or with an error — the Compressor API sends an HTTP POST request to the specified webhook URL.

  • The request body contains the same JSON structure returned by synchronous requests, including job metadata, output URLs, and file information.
  • Failed jobs return an error payload consistent with standard API error responses.

Request Headers

Webhook deliveries include the following headers by default:

User-Agent: Compressor/1.0 (+https://compressor.app)
Content-Type: application/json

These headers allow your system to reliably identify webhook traffic originating from the Compressor platform.

Response Requirements

Your webhook endpoint must return an HTTP 2xx status code to acknowledge successful receipt of the payload. The endpoint should respond as quickly as possible.

Webhook handlers should be treated as notification receivers rather than processing endpoints. Any time-consuming work (such as downloading files, database writes, or further transformations) should be performed asynchronously after acknowledging the request.

Timeouts and Reliability

Webhook delivery is designed for reliability across varying network conditions:

  • Endpoints are expected to respond within a short time window.
  • Non-2xx responses or network failures are treated as delivery failures.
  • Webhook deliveries may be retried automatically, so handlers should be idempotent.

Each job is identified by a stable id, which can be used to safely detect and ignore duplicate deliveries.

Security Considerations

  • Webhook URLs must be accessible over HTTPS.
  • Endpoints should validate incoming payloads and avoid trusting unauthenticated input.
  • Firewall or application-level rules may be used to restrict access to known webhook traffic.

Additional webhook authentication and verification mechanisms are described in advanced webhook documentation.

CSRF Protection

Webhook deliveries are server-to-server HTTP POST requests initiated by the Compressor platform. If your application enforces CSRF protection (common in web frameworks that assume browser form submissions), your webhook endpoint may reject requests that do not include a CSRF token.

Webhook endpoints should be treated as machine-to-machine integrations and typically must be exempt from CSRF checks.

To integrate safely:

  • Create a dedicated webhook route (for example: /webhooks/compressor) that is not used by browser forms.
  • Configure your framework to disable CSRF validation for that route.
  • Do not rely on cookies or browser sessions for webhook authentication.
On this page