Webhooks

​

Why use webhooks

Webhooks offer an efficient way to receive real-time updates on your video generation jobs. Instead of repeatedly polling for the status updates, webhooks notify you immediately when a job completes or fails.

​

Integrating webhooks

To utilize webhooks:

1. Specify a webhookUrl parameter when calling an API endpoints that support it.
2. Ensure your webhook endpoint can receive and handle HTTP POST requests.

When a job finishes (successfully or not), we’ll send an HTTP POST request to your specified webhookUrl with the job details.

​

Webhook payload

The webhook payload matches the format of the corresponding GET request for the job. For example, a webhook for the POST /generate endpoint will return data identical to the GET /generate/{id} endpoint:

{
  "id": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "status": "<string>",
  "model": "<string>",
  "input": [
    {
      "type": "<string>",
      "url": "<string>"
    }
  ],
  "webhookUrl": "<string>",
  "options": {},
  "stream": true,
  "outputUrl": "<string>",
  "error": "<string>"
}

By leveraging webhooks, you can streamline your workflow with non-blocking calls, allowing you to focus on other tasks while receiving job completion notifications.

​

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)

const express = require("express");
const { createHmac, timingSafeEqual } = require("crypto");

const app = express();

const WEBHOOK_SECRET = "whsec_";

app.use(express.json());

const verifySignature = (payload, signature, secret) => {
  try {
    if (!signature) {
      return false;
    }
    const [, timestamp, receivedSignature] =
      signature.match(/t=(\d+),v1=(.+)/) ?? [];
    if (!timestamp || !receivedSignature) {
      return false;
    }

    const expectedSignature = createHmac("sha256", secret)
      .update(`${timestamp}.${JSON.stringify(payload)}`)
      .digest("hex");

    // Timing-safe comparison to prevent timing attacks
    return timingSafeEqual(
      Buffer.from(receivedSignature),
      Buffer.from(expectedSignature)
    );
  } catch (error) {
    return false;
  }
};

app.post("/webhook", (req, res) => {
  const signature = req.headers["sync-signature"];

  if (!verifySignature(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(400).json({
      message: "Invalid signature",
    });
  }

  return res.status(200).json({
    message: "Webhook signature verified",
  });
});

app.listen(8080, () => {});