Webhooks

A webhook is an HTTPS URL of yours that the API POSTs an event to when something happens: a file is done or failed, a project stops, or its processing service fails. Each delivery is signed, so your server can tell it came from SyncWords, and repeated until your server takes it. Polling GET /projects/{id}/files keeps working, and stays the way to catch up after your server was down for longer than deliveries are retried.

Create a webhook

curl -s -X POST "$API/webhooks" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"url": "https://hooks.example.com/syncwords", "events": ["file.done", "file.failed", "project.stopped", "project.error"]}'

{
  "data": {
    "id": "wh_01m3n2t4k8b5x0c7d2e9f6g1h3",
    "url": "https://hooks.example.com/syncwords",
    "events": ["file.done", "file.failed", "project.stopped", "project.error"],
    "createdAt": "2026-09-28T09:00:00.000Z",
    "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
  }
}

The secret is shown only in this answer. Store it with your server’s other secrets; it is what you verify each delivery with. Lost it, or leaked it? Rotate it.

The URL must be https:// and reach a public address: private networks, loopback and link-local addresses are refused, when you create the webhook and again at every delivery, and so are host names without a dot and names under .local or .internal. An account has at most 10 webhooks, one per URL. A webhook receives the events that happen after it was created, for every project of the account.

Call	What it does
`GET /webhooks`	Your webhooks.
`GET /webhooks/{id}`	One of them.
`PATCH /webhooks/{id}`	Changes its `url`, its `events`, or both. The id and the secret stay; deliveries not yet made go to the new URL.
`DELETE /webhooks/{id}`	Stops it at once; deliveries not yet made are dropped.
`POST /webhooks/{id}/rotate-secret`	A new secret; the old one keeps signing for 24 hours. Rotate the secret.
`POST /webhooks/{id}/test`	Sends a `webhook.test` event now and answers what your server said.
`GET /webhooks/{id}/deliveries`	The deliveries of the past 7 days, newest first, with attempts and your server’s answers. Paged (`page`, `perPage`); `?status=pending`, `delivered` or `failed`.
`POST /webhooks/{id}/deliveries/{eventId}/retry`	Sends that delivery again now, with a fresh 24 hours of retries.

Events

Every delivery is a JSON body of the same shape:

{
  "id": "evt_01m3n2x5f1h2d9k7c3b8a6w4q0",
  "type": "file.done",
  "timestamp": "2026-09-28T10:00:04.000Z",
  "data": { … }
}

id is the event’s, the same on every attempt: keep the ids you have handled and drop a repeat. timestamp is when it happened. Events can arrive out of order; compare timestamp if the order matters to you. Payloads only grow. Fields may be added to data, and new event types added, without notice; none is removed or changes meaning. Ignore what you do not know. A change that would break that comes as a new event type (file.done.v2, say), sent beside the old one for as long as it takes to move.

`type`	When	`data`
`file.done`	A file finished processing.	`project`, and `file`: `name`, `hash`, `outputs`, `completedAt`
`file.failed`	A file could not be processed.	`project`, and `file`: `name`, `failureReason`, `failedAt`
`project.stopped`	A running project stopped.	`project`, and `reason`: `requested` (`POST …/stop`), `idle` (stopped 30 minutes after its last file, or after its service read `failed` for 2 hours) or `deleted`
`project.error`	The processing service did not start, or stopped working.	`project`, `reason` (`launch_failed` or `service_failed`) and `message`
`webhook.test`	You called `POST /webhooks/{id}/test`.	`webhook`: `id`, `url`

{
  "id": "evt_01m3n2x5f1h2d9k7c3b8a6w4q0",
  "type": "file.done",
  "timestamp": "2026-09-28T10:00:04.000Z",
  "data": {
    "project": { "id": "01m3k8jnrdw509457nhz7w81bq", "name": "Fishing Channel S01" },
    "file": {
      "name": "season 1/episode 01.mp4",
      "hash": "8b548db6",
      "outputs": [
        { "path": "season 1/episode 01.es.mp4", "available": true, "size": 81234567 }
      ],
      "completedAt": "2026-09-28T10:00:04.000Z"
    }
  }
}

{
  "id": "evt_01m3n30c2q7r4s9t6v1w8x3y5z",
  "type": "file.failed",
  "timestamp": "2026-09-28T10:02:11.000Z",
  "data": {
    "project": { "id": "01m3k8jnrdw509457nhz7w81bq", "name": "Fishing Channel S01" },
    "file": {
      "name": "season 1/episode 02.mp4",
      "failureReason": "Processing this file failed. Retry it, or contact support if it fails again.",
      "failedAt": "2026-09-28T10:02:11.000Z"
    }
  }
}

{
  "id": "evt_01m3n3d7a1b2c3d4e5f6g7h8j9",
  "type": "project.stopped",
  "timestamp": "2026-09-28T10:32:40.512Z",
  "data": {
    "project": { "id": "01m3k8jnrdw509457nhz7w81bq", "name": "Fishing Channel S01" },
    "reason": "idle"
  }
}

{
  "id": "evt_01m3n3k2m4n6p8q0r2s4t6v8w0",
  "type": "project.error",
  "timestamp": "2026-09-28T09:15:02.000Z",
  "data": {
    "project": { "id": "01m3k8jnrdw509457nhz7w81bq", "name": "Fishing Channel S01" },
    "reason": "service_failed",
    "message": "The processing service stopped working. Start the project again, or contact support if it keeps failing."
  }
}

file.done’s hash is the file’s processing key: the same for every run of that name in the project, retries and replacements included. Quote it to support; to tell runs apart, use completedAt, and to tell events apart, id. On file.done, download each output whose available is true with GET /projects/{id}/outputs/download?path=<path>. On file.failed, POST /projects/{id}/files/{name}/retry and start try it again. On project.error, POST /projects/{id}/start does. A project that reads a feed sends the same events. A file’s name is the one made from the feed item (4f1c2b9a7d3e.8a2b4c6d.mp4), and the files of an output feed are among its outputs, under feeds/<language>/. By the time file.done is sent, the output feed links the file, or will on its next rewrite, within 30 seconds. Such a project is never stopped for being idle, so it sends project.stopped with reason: "idle" only after its service has read failed for 2 hours.

Verify the signature

Each delivery carries three headers, as the Standard Webhooks specification has them:

Header	Value
`webhook-id`	The event’s `id`.
`webhook-timestamp`	When this attempt was sent, in seconds since 1970.
`webhook-signature`	`v1,` and the base64 HMAC-SHA256 of `<webhook-id>.<webhook-timestamp>.<body>`, keyed with the secret’s bytes: the base64 after `whsec_`. For 24 hours after a rotation, two of them, space-separated: the new secret’s first.

To verify one:

Read the body as raw bytes, before any JSON parsing: re-serialised JSON does not match.
Refuse a webhook-timestamp more than 5 minutes from your clock, so an old delivery cannot be replayed.
Compute the signature and compare it, in constant time, with each space-separated entry of webhook-signature.

A receiver that verifies, drops repeats, and answers at once:

import base64
import hashlib
import hmac
import json
import os
import time
from http.server import BaseHTTPRequestHandler, HTTPServer

SECRET = base64.b64decode(os.environ["SW_WEBHOOK_SECRET"].removeprefix("whsec_"))
TOLERANCE = 5 * 60
handled = set()  # use your database in production


def verified(headers, body: bytes) -> bool:
    msg_id = headers.get("webhook-id", "")
    timestamp = headers.get("webhook-timestamp", "")
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > TOLERANCE:
        return False
    signed = f"{msg_id}.{timestamp}.".encode() + body
    expected = "v1," + base64.b64encode(hmac.new(SECRET, signed, hashlib.sha256).digest()).decode()
    return any(
        hmac.compare_digest(expected, candidate)
        for candidate in headers.get("webhook-signature", "").split(" ")
    )


class Receiver(BaseHTTPRequestHandler):
    def do_POST(self):
        body = self.rfile.read(int(self.headers.get("content-length", 0)))
        if not verified(self.headers, body):
            self.send_response(401)
            self.end_headers()
            return
        event = json.loads(body)
        self.send_response(204)  # answer first, work after
        self.end_headers()
        if event["id"] in handled:
            return
        handled.add(event["id"])
        if event["type"] == "file.done":
            print("done:", event["data"]["file"]["name"])


HTTPServer(("", 8080), Receiver).serve_forever()

import { createHmac, timingSafeEqual } from 'node:crypto';
import { createServer } from 'node:http';

const SECRET = Buffer.from(process.env.SW_WEBHOOK_SECRET.replace(/^whsec_/, ''), 'base64');
const TOLERANCE = 5 * 60;
const handled = new Set(); // use your database in production

function verified(headers, body) {
  const id = headers['webhook-id'] ?? '';
  const timestamp = headers['webhook-timestamp'] ?? '';
  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE) {
    return false;
  }
  const expected = Buffer.from(
    'v1,' + createHmac('sha256', SECRET).update(`${id}.${timestamp}.`).update(body).digest('base64'),
  );
  return (headers['webhook-signature'] ?? '').split(' ').some((candidate) => {
    const given = Buffer.from(candidate);
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

createServer((request, response) => {
  const chunks = [];
  request.on('data', (chunk) => chunks.push(chunk));
  request.on('end', () => {
    const body = Buffer.concat(chunks);
    if (!verified(request.headers, body)) {
      response.writeHead(401).end();
      return;
    }
    const event = JSON.parse(body);
    response.writeHead(204).end(); // answer first, work after
    if (handled.has(event.id)) return;
    handled.add(event.id);
    if (event.type === 'file.done') console.log('done:', event.data.file.name);
  });
}).listen(8080);

The Standard Webhooks libraries verify the same headers: pip install standardwebhooks, npm install standardwebhooks, and others for most languages.

Serve the receiver behind your usual HTTPS proxy or load balancer: the URL you register must be https://. POST /webhooks/{id}/test checks the whole path, signature included.

Rotate the secret

curl -s -X POST "$API/webhooks/$WEBHOOK/rotate-secret" -H "$AUTH"

The answer carries the new secret, shown only there, and previousSecretExpiresAt. Until then every delivery is signed with both secrets, so:

Rotate, and give your server the new secret beside the old one.
Your server accepts a delivery when either secret’s signature matches (the receivers above already compare every entry of webhook-signature).
Once the new secret is in place everywhere — within 24 hours — drop the old one.

Retries

A delivery is made when your server answers with a 2xx status within 10 seconds of the attempt starting: connecting, TLS and the status line all count, and the body you send back is not waited for. Anything else — another status, a redirect (redirects are not followed), a timeout, a refused connection — is tried again:

Attempt	After the previous one
2	30 seconds
3	2 minutes
4	10 minutes
5	30 minutes
6 and on	every hour

A delivery still failing 24 hours after its event is given up, and shows status: "failed" in GET /webhooks/{id}/deliveries?status=failed. Each delivery there has lastStatus (your server’s last HTTP status, or null when it could not be reached) and lastError. Once your server is fixed, POST /webhooks/{id}/deliveries/{eventId}/retry sends one again, with another 24 hours of retries; deliveries are kept 7 days. After a longer outage, catch up by listing your projects’ files. Deliveries to one webhook go one at a time, and a few per webhook in each round: when your server does not answer, the rest of its deliveries wait for the next round rather than each waiting out its own timeout. Other accounts’ webhooks are not slowed by yours, nor yours by theirs. So that retries do no harm:

Answer fast, then do the work: queue the event and return 204.
Drop repeats by id: an attempt your server handled but answered too slowly is sent again.
Do not depend on order.

Limits


Webhooks	10 per account, one per URL.
URL	`https://`, at most 2048 characters, no user name or password, a public address.
Answer	A `2xx` status within 10 seconds of the attempt starting.
Retries	For 24 hours after the event, or after `POST …/retry`.
Previous secret	Signs beside the new one for 24 hours after a rotation.
Delivery history	7 days.

Get started

Concepts

Configure a project

Upload media

Examples

Going to production

Help

Create a webhook

Events

Verify the signature

Rotate the secret

Retries

Limits

​Create a webhook

​Events

​Verify the signature

​Rotate the secret

​Retries

​Limits

Create a webhook

Events

Verify the signature

Rotate the secret

Retries

Limits