Webhooks

Webhooks allow you to receive status update notifications for your jobs and tasks. You can create webhooks using the User Dashboard.

Events

In all three cases, the payload includes the Job. See an example on the right side.

Failing Webhooks

If your webhook endpoint returns a 4XX or 5XX HTTP status code, the webhook event will be retried up to 3 times (in 30-minute intervals). If you have enabled the "Webhook unreachable" notification from your user dashboard, you will also receive an email when a webhook fails.

If the webhook endpoint returns a 410 status code, the webhook will be automatically disabled. It can be re-enabled manually from the User Dashboard at any time.

Signing Webhooks

To verify that a webhook originates from FreeConvert.com, you should validate its signature. Each webhook is cryptographically signed using a unique signing secret. Use this key to confirm that the webhook is coming from us. You can retrieve this secret by clicking the edit icon next to your webhook.

The FreeConvert-Signature header contains a hash-based message authentication code (HMAC) using SHA-256. The following PHP example demonstrates how to calculate this signature for validation:

$signature = hash_hmac('sha256', $payload, $signingSecret);

$signingSecret can be found in the webhook settings page of the user dashboard (click show in the SECRET column). $payload is the full request body (the JSON string) sent to your webhook endpoint.