API reference / Webhooks

Add a webhook endpoint

POST/v1/webhooks

url is an HTTPS URL on port 443 at a public address, without credentials, at most 2,048 characters. Leave out events to receive every event type, including ones added later (allEvents is then true). The response includes the signing secret (whsec_…) once; requests are signed per Standard Webhooks. A workspace has at most 10 endpoints (409 webhook_limit) and adds or repoints them at most 20 times an hour (429 rate_limited). Its owners and admins are emailed which endpoint was added and by whom.

Request

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"
  }'
import os, requests

response = requests.post(
    f"{os.environ['BLITFRAME']}/webhooks",
    headers={"Authorization": f"Bearer {os.environ['BLITFRAME_API_KEY']}"},
    json={
        "url": "https://example.com/blitframe-webhook",
        "events": ["render.succeeded", "render.failed"],
        "description": "Production",
    },
)
print(response.json())
const response = await fetch(`${process.env.BLITFRAME}/webhooks`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BLITFRAME_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://example.com/blitframe-webhook",
    events: ["render.succeeded", "render.failed"],
    description: "Production",
  }),
});
console.log(await response.json());
<?php
$request = curl_init(getenv("BLITFRAME") . "/webhooks");
curl_setopt_array($request, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BLITFRAME_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => '{
      "url": "https://example.com/blitframe-webhook",
      "events": ["render.succeeded", "render.failed"],
      "description": "Production"
    }',
]);
$response = curl_exec($request);
echo $response;
require "net/http"

uri = URI(ENV["BLITFRAME"] + '/webhooks')
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer " + ENV["BLITFRAME_API_KEY"]
request["Content-Type"] = "application/json"
request.body = '{
  "url": "https://example.com/blitframe-webhook",
  "events": ["render.succeeded", "render.failed"],
  "description": "Production"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
	  "url": "https://example.com/blitframe-webhook",
	  "events": ["render.succeeded", "render.failed"],
	  "description": "Production"
	}`)
	request, err := http.NewRequest("POST", os.Getenv("BLITFRAME")+"/webhooks", body)
	if err != nil {
		panic(err)
	}
	request.Header.Set("Authorization", "Bearer "+os.Getenv("BLITFRAME_API_KEY"))
	request.Header.Set("Content-Type", "application/json")
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()
	text, _ := io.ReadAll(response.Body)
	fmt.Println(string(text))
}
using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post,
    Environment.GetEnvironmentVariable("BLITFRAME") + "/webhooks");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLITFRAME_API_KEY"));
request.Content = new StringContent(
    """
    {
      "url": "https://example.com/blitframe-webhook",
      "events": ["render.succeeded", "render.failed"],
      "description": "Production"
    }
    """, Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        var request = HttpRequest.newBuilder(URI.create(System.getenv("BLITFRAME") + "/webhooks"))
            .header("Authorization", "Bearer " + System.getenv("BLITFRAME_API_KEY"))
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString("""
                {
                  "url": "https://example.com/blitframe-webhook",
                  "events": ["render.succeeded", "render.failed"],
                  "description": "Production"
                }
                """))
            .build();
        var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Headers

  • AuthorizationBearer Blitframe API keyrequired

    API key from the developer console.

Body

application/json · required · CreateWebhookRequest

  • urlstringrequired
  • eventsarray of WebhookEventType or null

    Each one of render.succeeded render.failed render.cancelled download_archive.ready download_archive.failed version_export.ready version_export.failed balance.low webhook.test

  • descriptionstring or null

Try it

POST/v1/webhooks

Used for the requests you send from this page only. It is not saved.

This sends a real request to your workspace: a render spends render seconds, and a delete is final.

Response

Send the request to see the answer here.

Responses

  • 201 Created

application/json · WebhookDto

  • idstring (uuid)
  • urlstring
  • descriptionstring or null
  • allEventsboolean
  • eventsarray of WebhookEventType

    Each one of render.succeeded render.failed render.cancelled download_archive.ready download_archive.failed version_export.ready version_export.failed balance.low webhook.test

  • enabledboolean
  • disabledReasonstring or null
  • disabledAtstring (date-time) or null
  • previousSecretExpiresAtstring (date-time) or null
  • createdAtstring (date-time)
  • secretstring or null

Errors

  • 400 Bad Request
  • 401 Unauthorized
  • 404 Not Found
  • 409 Conflict
  • 429 Too Many Requests

application/json · ErrorResponse

  • ApiError fields
    • codestring
    • messagestring

Errors lists the error codes and says when to retry.