Webhooks: Get Told When a Render Finishes
Set up video.completed and video.failed webhooks, verify their signatures, and understand retries.
What webhooks do
Instead of checking a video again and again, you can give us the address of your server. When an API render finishes, we send your server a signed POST request with the result. There are two events:
| Event | Sent when | Includes |
|---|---|---|
| video.completed | A render finished successfully. | The video id, length, resolution, seed, your metadata and a download address. |
| video.failed | A render failed. | The video id, an error message and how many credits went back to your balance. |
Tip
- The download address in a webhook needs your API key and always leads to a fresh download link, so it still works if the webhook arrives late.
Adding an endpoint
Endpoints are managed in the Webhooks section of /developer, or through the API. You can have up to 5 endpoints.
- 1Type your server address, for example https://your-server.com/ballengine/webhook.
- 2Tick the events you want: video.completed, video.failed, or both.
- 3Press Add Endpoint.
- 4Copy the signing secret from the green box and store it on your server. It is shown only once. Press "I saved it: dismiss".
- 5Press Send test. The endpoint shows "Test delivered" with the status code, or "Test failed" with the reason.
Technical parameters
- The address must use https on the normal port, use a public host name (not an IP address or a local name), contain no username or password, and point at your own server. It can be up to 500 characters.
Checking that a webhook came from us
Every webhook carries a BallEngine-Signature header that looks like t=<timestamp>,v1=<signature>. Your server should check it before trusting the request:
- 1Read the raw request body exactly as it arrived, before parsing the JSON.
- 2Join the timestamp, a dot, and the raw body.
- 3Compute an HMAC-SHA256 of that text using your signing secret, as hex.
- 4Compare it with v1 using a constant-time comparison.
- 5Reject the request if the timestamp is more than 5 minutes away from your server clock.
Tip
- A ready-to-use Node.js example is in the Webhooks part of /developer/docs.
- If signatures never match, the usual cause is a framework that parsed and re-serialised the JSON before you hashed it. Hash the raw bytes.
Responding and handling repeats
Answer with any 2xx status within 10 seconds and the delivery counts as done. Do slow work after you answer, not before.
The same event can arrive more than once. Each event has an id (also sent in the BallEngine-Event-Id header); store the ids you have handled and ignore repeats.
In rare cases a render reported as failed finishes after all. You then get a video.completed after the video.failed. The later event is the correct one.
Retries and switched-off endpoints
If your server does not answer with a 2xx in time, we try again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours: about 32 hours in total.
| An endpoint is switched off when | What is switched off |
|---|---|
| It fails 20 deliveries in a row | That endpoint |
| It is sent more than 200 deliveries in one hour | That endpoint |
| Test or resend requests keep coming after the limit: 10 refused in one hour | Every endpoint on your account |
Tip
- A switched-off endpoint shows the reason in red on /developer and receives nothing, test events included.
- Only you can turn it back on: sign in to /developer and press Turn on. There is no API call for it, so a script that went wrong cannot switch its own endpoint back on.
- Fix whatever caused it first. If the cause is still there, the endpoint is switched off again.
How often you can test, resend and add endpoints
Each of these makes our server send a request to an address you chose, so they are limited per account. The limits are shared between /developer and the API.
| Action | Per minute | Per hour |
|---|---|---|
| Send test | 3 | 15 |
| Send again (resend) | 5 | 30 |
| Add an endpoint | 5 | 20 |
Tip
- Going over a limit answers rate_limited with retry_after. Wait that long instead of trying again straight away: repeated refused tests or resends switch off every endpoint on your account.
Webhook controls on /developer
| Control | What it does |
|---|---|
| Send test | Sends a test event to the endpoint right now and shows the result. Up to 3 a minute and 15 an hour. |
| Turn on | Shown instead of Send test on a switched-off endpoint, with the reason it was switched off. Turns it back on. This is the only way to turn one back on. |
| New signing secret (circular arrow) | Creates a new secret. The old one stops working immediately, so update your server first or be ready to right after. |
| Delete (bin) | Removes the endpoint. Events stop being sent to it immediately. |
| Recent deliveries | Each delivery with its event, video, endpoint, status (Delivered, Retrying or Failed, with the number of tries) and last try time. Hover or read the line under a failed one for the error. |
| Send again | Re-sends a delivered or failed event. |
More from BallEngine
Guides, plans and answers for making your videos.