Webhooks
Webhooks offer an efficient way to receive status updates on your generation jobs. Instead of polling for the status updates, webhooks notify you when a job completes or fails.
Integrating webhooks
To utilize webhooks:
- Specify a
webhookUrl
parameter when calling an API endpoints that support it. - Ensure your webhook endpoint can receive and handle HTTP
POST
requests and can consume the Webhook Payload for status updates.
For security purposes, your webhook URL must be configured to accept and
process HTTPS POST
requests.
By leveraging webhooks, you can streamline your workflow with non-blocking calls, allowing you to focus on other tasks while receiving job completion notifications.
Error Handling in Webhooks
When a generation fails, the webhook payload will include error information in two fields:
error
: A human-readable error message describing what went wrongerror_code
: A specific error code that can be used for programmatic error handling (see the Error Handling guide for a complete list of error codes)
This improved error structure allows you to both display meaningful messages to users and implement specific error handling logic based on the error codes.
Verify webhook signatures
To ensure webhook requests are coming from Sync, we sign each webhook request with a signature. The signature is included in the Sync-Signature
header.
To verify signatures, use your signing secret.
The signature is made out of 2 components:
- Timestamp (at the time of sending the event)
- Signature hash (timestamp and the JSON payload)