Webhooks
View as MarkdownGet a request on your server when a render, a download archive or a version export finishes, or when your render seconds run low. You react to the event instead of polling.
Add an endpoint
An endpoint is the URL on your server that Blitframe calls. POST /v1/webhooks adds one, and so does Console → Webhooks. BLITFRAME and BLITFRAME_API_KEY are set as in the quickstart, and its Before you start lists what each language needs.
WEBHOOK=$(curl -s -X POST $BLITFRAME/webhooks \
-H "Authorization: Bearer $BLITFRAME_API_KEY" -H "Content-Type: application/json" \
-d '{"url":"https://example.com/blitframe-webhook","events":["render.succeeded","render.failed"],"description":"Production"}')
WEBHOOK_ID=$(echo "$WEBHOOK" | jq -r .id)
echo "$WEBHOOK" | jq -r .secret
import os, requests
api = os.environ["BLITFRAME"]
headers = {"Authorization": f"Bearer {os.environ['BLITFRAME_API_KEY']}"}
webhook = requests.post(f"{api}/webhooks", headers=headers, json={
"url": "https://example.com/blitframe-webhook",
"events": ["render.succeeded", "render.failed"],
"description": "Production",
}).json()
webhook_id = webhook["id"]
print(webhook["secret"])
const api = process.env.BLITFRAME;
const headers = { Authorization: `Bearer ${process.env.BLITFRAME_API_KEY}` };
const json = { ...headers, "Content-Type": "application/json" };
const webhook = await (
await fetch(`${api}/webhooks`, {
method: "POST",
headers: json,
body: JSON.stringify({
url: "https://example.com/blitframe-webhook",
events: ["render.succeeded", "render.failed"],
description: "Production",
}),
})
).json();
const webhookId = webhook.id;
console.log(webhook.secret);
<?php
function call(string $method, string $path, ?array $body = null, array $headers = []): array {
$headers[] = "Authorization: Bearer " . getenv("BLITFRAME_API_KEY");
$ch = curl_init(getenv("BLITFRAME") . $path);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => $method]);
if ($body !== null) {
$headers[] = "Content-Type: application/json";
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
}
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
return json_decode(curl_exec($ch), true);
}
$webhook = call("POST", "/webhooks", [
"url" => "https://example.com/blitframe-webhook",
"events" => ["render.succeeded", "render.failed"],
"description" => "Production",
]);
$webhookId = $webhook["id"];
echo $webhook["secret"], "\n";
require "net/http"
require "json"
def call(method, path, body = nil, headers = {})
uri = URI(ENV["BLITFRAME"] + path)
headers = { "Authorization" => "Bearer #{ENV["BLITFRAME_API_KEY"]}" }.merge(headers)
headers["Content-Type"] = "application/json" if body
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
http.send_request(method, uri.request_uri, body&.to_json, headers)
end
JSON.parse(response.body)
end
webhook = call("POST", "/webhooks", {
url: "https://example.com/blitframe-webhook",
events: ["render.succeeded", "render.failed"],
description: "Production",
})
webhook_id = webhook["id"]
puts webhook["secret"]
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
)
func call(method, path string, body any, headers map[string]string) map[string]any {
var payload bytes.Buffer
if body != nil {
if err := json.NewEncoder(&payload).Encode(body); err != nil {
panic(err)
}
}
req, err := http.NewRequest(method, os.Getenv("BLITFRAME")+path, &payload)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("BLITFRAME_API_KEY"))
if body != nil {
req.Header.Set("Content-Type", "application/json")
}
for name, value := range headers {
req.Header.Set(name, value)
}
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
var out map[string]any
if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
panic(err)
}
return out
}
func main() {
webhook := call("POST", "/webhooks", map[string]any{
"url": "https://example.com/blitframe-webhook",
"events": []string{"render.succeeded", "render.failed"},
"description": "Production",
}, nil)
webhookID := webhook["id"].(string)
fmt.Println(webhook["secret"])
_ = webhookID // the next examples use it
}
using System.Net.Http.Json;
using System.Text.Json.Nodes;
var api = Environment.GetEnvironmentVariable("BLITFRAME");
var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new("Bearer", Environment.GetEnvironmentVariable("BLITFRAME_API_KEY"));
async Task<JsonNode> call(HttpMethod method, string path, object? body = null, params (string Name, string Value)[] headers)
{
var request = new HttpRequestMessage(method, api + path);
if (body != null) request.Content = JsonContent.Create(body);
foreach (var (name, value) in headers) request.Headers.Add(name, value);
var response = await http.SendAsync(request);
return (await response.Content.ReadFromJsonAsync<JsonNode>())!;
}
var webhook = await call(HttpMethod.Post, "/webhooks", new
{
url = "https://example.com/blitframe-webhook",
events = new[] { "render.succeeded", "render.failed" },
description = "Production",
});
var webhookId = webhook["id"]!.GetValue<string>();
Console.WriteLine(webhook["secret"]);
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
static final ObjectMapper json = new ObjectMapper();
static JsonNode call(String method, String path, String body, String... headers) throws Exception {
HttpRequest.Builder request = HttpRequest.newBuilder(URI.create(System.getenv("BLITFRAME") + path))
.header("Authorization", "Bearer " + System.getenv("BLITFRAME_API_KEY"))
.method(method, body == null ? HttpRequest.BodyPublishers.noBody() : HttpRequest.BodyPublishers.ofString(body));
if (body != null) request.header("Content-Type", "application/json");
if (headers.length > 0) request.headers(headers);
HttpResponse<String> response = HttpClient.newHttpClient().send(request.build(), HttpResponse.BodyHandlers.ofString());
return json.readTree(response.body());
}
public static void main(String[] args) throws Exception {
JsonNode webhook = call("POST", "/webhooks", """
{"url": "https://example.com/blitframe-webhook",
"events": ["render.succeeded", "render.failed"],
"description": "Production"}
""");
String webhookId = webhook.get("id").asText();
System.out.println(webhook.get("secret").asText());
}
}
Store the secret (whsec_…) it prints. The response shows it only once, and you need it to verify signatures.
The other examples on this page continue from this one, in the same shell or file. They reuse the endpoint's id from WEBHOOK_ID (webhook_id, webhookId or webhookID in the other languages). In Go and Java, they go inside main.
| Field | Values |
|---|---|
url |
Required. HTTPS on the standard port (443), resolving to a public address. Blitframe refuses localhost, private IP addresses, host names that resolve to one, and URLs with a user name or password. Up to 2,048 characters. A host name that only later resolves to a private address stays, but every delivery to it fails, and its lastError starts with "Webhook host resolves to a private address." |
events |
The event types to receive. Leave it out to receive all of them, including types added later. The endpoint then shows "allEvents": true. |
description |
An optional note, up to 200 characters. |
The response is 201 Created with the endpoint and its secret. A workspace can have up to 10 endpoints, and add or repoint them 20 times an hour (limits).
Events carry download links to your videos. So whenever an endpoint is added or its url changes, the workspace's owners and admins get an email. It names the endpoint and who set it up: a person in the console, an API key, or an app connected over MCP.
Verifying signatures
Blitframe signs every request per the Standard Webhooks specification, so its official libraries verify Blitframe requests as they are. Each request carries:
webhook-id: 0d7c5a1e-6f3b-4c2d-9e8a-1b2c3d4e5f60
webhook-timestamp: 1793800800
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
Verify the raw request body, exactly as received, before you parse the JSON. Reject requests whose timestamp is more than 5 minutes from your clock. The libraries do both.
Each example is a complete receiver on port 3000. It reads the secret from BLITFRAME_WEBHOOK_SECRET, verifies each request, prints the event type and answers 204, or 400 when the signature or timestamp is wrong.
Node (npm install standardwebhooks, then save as receiver.mjs and run node receiver.mjs):
import { createServer } from "node:http";
import { Webhook } from "standardwebhooks";
const wh = new Webhook(process.env.BLITFRAME_WEBHOOK_SECRET);
createServer(async (req, res) => {
const chunks = [];
for await (const chunk of req) chunks.push(chunk);
const rawBody = Buffer.concat(chunks).toString("utf8");
try {
const event = wh.verify(rawBody, req.headers);
console.log(event.type);
res.writeHead(204).end();
} catch {
res.writeHead(400).end();
}
}).listen(3000);
Python (pip install standardwebhooks, then save as receiver.py and run python receiver.py):
import os
from http.server import BaseHTTPRequestHandler, HTTPServer
from standardwebhooks.webhooks import Webhook
wh = Webhook(os.environ["BLITFRAME_WEBHOOK_SECRET"])
class Receiver(BaseHTTPRequestHandler):
def do_POST(self):
raw_body = self.rfile.read(int(self.headers["Content-Length"]))
try:
event = wh.verify(raw_body, dict(self.headers))
except Exception:
self.send_response(400)
else:
print(event["type"])
self.send_response(204)
self.end_headers()
HTTPServer(("", 3000), Receiver).serve_forever()
Your endpoint must be reachable over HTTPS at a public address, so put the receiver behind your web server or a tunnel.
To verify by hand:
- Remove the
whsec_prefix from your secret and Base64-decode the rest. That is the HMAC key. - Compute HMAC-SHA256 with that key over
{webhook-id}.{webhook-timestamp}.{raw body}, and Base64-encode it. webhook-signatureis a space-separated list ofv1,<signature>entries. Accept the request if any entry's signature equals yours, compared in constant time.- Reject the request if
webhook-timestamp(Unix seconds) is more than 5 minutes from your clock.
Rotate the secret
POST /v1/webhooks/{id}/rotate-secret returns a new secret, shown once, and previousSecretExpiresAt.
During the grace period, webhook-signature carries two entries, one per secret, so you can deploy the new secret without missing events. After it, only the new secret signs. Rotating again within the grace period drops the oldest secret at once: at most two ever sign.
The grace period is 24 hours, unless you send gracePeriodSeconds (0 to 86,400):
{ "gracePeriodSeconds": 0 }
0 stops the previous secret at once, for a secret that leaked. previousSecretExpiresAt is then null. Deploy the new secret quickly: until you do, your server rejects deliveries, and they are retried.
Send a test event
POST /v1/webhooks/{id}/test queues a webhook.test event for the endpoint, whatever event types it picked. The event is signed, logged and retried like any other. So it shows whether your server receives requests and verifies their signatures.
curl -s -X POST $BLITFRAME/webhooks/$WEBHOOK_ID/test \
-H "Authorization: Bearer $BLITFRAME_API_KEY" | jq '{messageId, status}'
delivery = requests.post(f"{api}/webhooks/{webhook_id}/test", headers=headers).json()
print(delivery["messageId"], delivery["status"])
const delivery = await (await fetch(`${api}/webhooks/${webhookId}/test`, { method: "POST", headers })).json();
console.log(delivery.messageId, delivery.status);
$delivery = call("POST", "/webhooks/$webhookId/test");
echo $delivery["messageId"], " ", $delivery["status"], "\n";
delivery = call("POST", "/webhooks/#{webhook_id}/test")
p delivery["messageId"], delivery["status"]
delivery := call("POST", "/webhooks/"+webhookID+"/test", nil, nil)
fmt.Println(delivery["messageId"], delivery["status"])
var delivery = await call(HttpMethod.Post, $"/webhooks/{webhookId}/test");
Console.WriteLine($"{delivery["messageId"]} {delivery["status"]}");
JsonNode delivery = call("POST", "/webhooks/" + webhookId + "/test", null);
System.out.println(delivery.get("messageId").asText() + " " + delivery.get("status").asText());
The API answers 202 Accepted with the queued delivery, as the delivery log lists it. Its messageId is the event's id. The endpoint must be enabled. An endpoint takes at most 30 test events and redeliveries an hour, and none while 100 of its deliveries are waiting: past that you get 429 rate_limited. Your server receives:
{
"id": "6b1f0c2e-3a4d-4e5f-8a9b-0c1d2e3f4a5b",
"type": "webhook.test",
"createdAt": "2026-11-08T09:00:00+00:00",
"data": { "webhookId": "…" }
}
Events
Every request is a JSON POST:
{
"id": "0d7c5a1e-6f3b-4c2d-9e8a-1b2c3d4e5f60",
"type": "render.succeeded",
"createdAt": "2026-11-04T14:00:00+00:00",
"data": { "id": "…", "status": "succeeded", "output": { "mp4Url": "https://…" } }
}
type |
When | data |
|---|---|---|
render.succeeded |
A render succeeded. | The render, with the sourceVersionId and versionId it was made from. A video render has output.mp4Url and output.posterUrl. A frame render's links come only from GET /v1/renders/{id}. |
render.failed |
A render failed. | The render. error says why, and refundedSeconds shows the refund. |
render.cancelled |
A render was cancelled. | The render. refundedSeconds shows the refund. |
download_archive.ready |
A download archive is built. | The archive, as GET /v1/renders/download-archive/{id} returns it. url downloads it. |
download_archive.failed |
A download archive could not be built. | The archive. error says why. |
version_export.ready |
A version export is built. | The export, as GET /v1/versions/{versionId}/export/{exportId} returns it. url downloads it. |
version_export.failed |
A version export could not be built. | The export. error says why. |
balance.low |
Your render seconds fell below the workspace's low-balance warning, which says when it is sent again. | Your balance and limits, as GET /v1/usage returns them. |
webhook.test |
You asked for a test event. It can't be picked in events. |
{ "webhookId": "…" } |
In render.succeeded, output.hlsUrl and output.frameUrls are null. In render.failed and render.cancelled, output itself is null. Render events leave out replacements. Get the render with GET /v1/renders/{id} for its HLS playlist, frame links and replacements.
Each delivery attempt of a render, archive or export event carries the object as it is at that moment, with fresh download links. Event details covers deleted objects and render versions.
Delivery
| Topic | Rule |
|---|---|
| Answer fast | Respond with any 2xx status within 20 seconds. Blitframe ignores the body of a 2xx answer, and keeps the first 1 KB of any other answer in the delivery log. |
| Redirects | Blitframe does not follow them, so a 3xx answer counts as a failed delivery. |
| Retries | A failed delivery is retried 9 more times, over about 3 days. The waits are 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, 14 hours, 20 hours and 24 hours. |
Retry-After |
On 429 or 503, Blitframe waits for a Retry-After header longer than the next gap, up to 24 hours. |
410 Gone |
Disables the endpoint at once. |
| Failing endpoints | When an endpoint has accepted no delivery for a day, the workspace's owners, admins and developers get a warning email, once for each run of failures. Blitframe disables an endpoint that has accepted none for the whole 3 days of retries. |
| Duplicates and order | Events can arrive more than once or out of order. Use the webhook-id header, which equals the body's id, to skip duplicates. |
| Load | Blitframe sends up to 10 requests to one endpoint at a time. An endpoint that stops answering in another workspace can't hold up yours. |
Each request also carries a Blitframe-Event header with the event type, and the user agent Blitframe-Webhooks/1.0.
Delivery log and redelivery
GET /v1/webhooks/{id}/deliveries lists the endpoint's deliveries of the last 30 days, newest first. Pass limit (default 50, up to 1,000), and pass next as before for older ones.
| Field | Meaning |
|---|---|
id |
The delivery's id, the deliveryId to redeliver. |
messageId |
The webhook-id it was sent with. |
eventType |
The event type. |
status |
pending, delivered or failed. |
attempts |
Attempts made so far. |
lastStatusCode, lastError, lastResponse |
The last attempt's HTTP status, its error, and the first 1 KB of a failed answer. |
createdAt, lastAttemptAt, nextAttemptAt, deliveredAt |
When it was queued, last tried, will next be tried (pending only) and delivered. |
POST /v1/webhooks/{id}/deliveries/{deliveryId}/redeliver queues the event again as a new delivery with the same webhook-id. So a receiver that skips duplicates still processes it once. It answers 202 Accepted with the new delivery. The endpoint must be enabled, or you get 409 webhook_disabled. Redeliveries count toward the same 30 an hour as test events.
Resend what an endpoint missed
After an outage, POST /v1/webhooks/{id}/recover queues again every event in the delivery log that never reached the endpoint, once each. Each keeps its original webhook-id. Events that were delivered later, or are already queued again, are skipped.
curl -s -X POST $BLITFRAME/webhooks/$WEBHOOK_ID/recover \
-H "Authorization: Bearer $BLITFRAME_API_KEY" -H "Content-Type: application/json" \
-d '{"since":"2026-11-01T00:00:00Z"}' | jq .queued
recovered = requests.post(f"{api}/webhooks/{webhook_id}/recover", headers=headers, json={"since": "2026-11-01T00:00:00Z"}).json()
print(recovered["queued"])
const recovered = await (
await fetch(`${api}/webhooks/${webhookId}/recover`, {
method: "POST",
headers: json,
body: JSON.stringify({ since: "2026-11-01T00:00:00Z" }),
})
).json();
console.log(recovered.queued);
$recovered = call("POST", "/webhooks/$webhookId/recover", ["since" => "2026-11-01T00:00:00Z"]);
echo $recovered["queued"], "\n";
recovered = call("POST", "/webhooks/#{webhook_id}/recover", { since: "2026-11-01T00:00:00Z" })
p recovered["queued"]
recovered := call("POST", "/webhooks/"+webhookID+"/recover", map[string]any{"since": "2026-11-01T00:00:00Z"}, nil)
fmt.Println(recovered["queued"])
var recovered = await call(HttpMethod.Post, $"/webhooks/{webhookId}/recover", new { since = "2026-11-01T00:00:00Z" });
Console.WriteLine(recovered["queued"]);
JsonNode recovered = call("POST", "/webhooks/" + webhookId + "/recover", """
{"since": "2026-11-01T00:00:00Z"}
""");
System.out.println(recovered.get("queued").asInt());
since resends only events logged from then on. Leave it out for the whole 30-day log. The answer is 202 Accepted with the number queued: { "queued": 12 }. The endpoint must be enabled. In the console, enabling an endpoint offers the same.
An event raised while the endpoint was disabled was never queued for it, so it is not in its delivery log and nothing can resend it. Read those renders, archives and exports from the API.
Manage endpoints
You can also manage endpoints in Console → Webhooks.
| Method | Path | Does |
|---|---|---|
GET |
/v1/webhooks |
List endpoints (never their secrets) |
GET |
/v1/webhooks/{id} |
Get one endpoint |
PATCH |
/v1/webhooks/{id} |
Change url, events, allEvents, enabled or description |
DELETE |
/v1/webhooks/{id} |
Remove the endpoint, its queued deliveries and its delivery log |
POST |
/v1/webhooks/{id}/rotate-secret |
Issue a new signing secret |
GET |
/v1/webhooks/{id}/deliveries |
Delivery log |
POST |
/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver |
Send an event again |
POST |
/v1/webhooks/{id}/test |
Send a test event |
POST |
/v1/webhooks/{id}/recover |
Resend the events it missed |
PATCH changes only the fields you send. This one also disables the endpoint:
curl -s -X PATCH $BLITFRAME/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $BLITFRAME_API_KEY" -H "Content-Type: application/json" \
-d '{"events":["render.succeeded","download_archive.ready"],"enabled":false}' | jq '{enabled, events}'
updated = requests.patch(f"{api}/webhooks/{webhook_id}", headers=headers,
json={"events": ["render.succeeded", "download_archive.ready"], "enabled": False}).json()
print(updated["enabled"], updated["events"])
const updated = await (
await fetch(`${api}/webhooks/${webhookId}`, {
method: "PATCH",
headers: json,
body: JSON.stringify({ events: ["render.succeeded", "download_archive.ready"], enabled: false }),
})
).json();
console.log(updated.enabled, updated.events);
$updated = call("PATCH", "/webhooks/$webhookId", [
"events" => ["render.succeeded", "download_archive.ready"],
"enabled" => false,
]);
var_dump($updated["enabled"], $updated["events"]);
updated = call("PATCH", "/webhooks/#{webhook_id}", {
events: ["render.succeeded", "download_archive.ready"],
enabled: false,
})
p updated["enabled"], updated["events"]
updated := call("PATCH", "/webhooks/"+webhookID, map[string]any{
"events": []string{"render.succeeded", "download_archive.ready"},
"enabled": false,
}, nil)
fmt.Println(updated["enabled"], updated["events"])
var updated = await call(HttpMethod.Patch, $"/webhooks/{webhookId}", new
{
events = new[] { "render.succeeded", "download_archive.ready" },
enabled = false,
});
var events = updated["events"]!.AsArray().Select(e => (string?)e);
Console.WriteLine($"{updated["enabled"]} [{string.Join(", ", events)}]");
JsonNode updated = call("PATCH", "/webhooks/" + webhookId, """
{"events": ["render.succeeded", "download_archive.ready"], "enabled": false}
""");
System.out.println(updated.get("enabled") + " " + updated.get("events"));
- Send
descriptionas an empty string to clear it. - Send
"allEvents": trueinstead ofeventsto receive every event type again, including types added later. "enabled": falsedisables the endpoint: new events skip it, and its queued retries stop. ItsdisabledReasonbecomes "Disabled in the console or through the API.", and no email is sent."enabled": trueturns it back on.
Refused updates lists the bodies PATCH refuses.
When Blitframe disables an endpoint itself (see Delivery), disabledReason says why, and the workspace's owners, admins and developers get an email. Fix the endpoint, enable it, and resend what it missed.
Details
Event details
- In render events,
sourceVersionIdis always set.versionIdisnullonly when the render failed or was cancelled before the version for its replacements was made. - If the render, archive or export was deleted, an attempt sends the payload stored when the event was raised, so its download links can be out of date.
Refused updates
PATCH answers 400 invalid_request when the body:
- sends none of
url,events,allEvents,enabledanddescription, - sends
"allEvents": false, orallEventstogether withevents, - sends an empty
eventslist.