Skip to main content

🌐 Webhooks

In this section, we detail the webhook notifications for the ZapCap API, covering the setup, structure, and processing of webhook messages.

Overview​

Webhooks are a powerful way to get notified about the status of your video tasks. They allow you to receive real-time updates when specific events occur within the ZapCap API.

Notification Setup​

When creating a video task, you can configure webhook notifications to receive updates on task status changes. This is specified in the notification object when creating a videoTask.

Example Notification Object​

"notification": {
    "type": "webhook",
    "notificationsFor": ["transcript", "render", "renderProgress"],
    "recipient": "https://example.com/api/webhook/zapcap"
}

Handling Webhook Messages​

Notification Payload​

The payload structure depends on the type of notification (NotificationFor) you have subscribed to. The possible values are transcript, render, and renderProgress.

Transcript Notification​

If the notification is for a transcript task:

{
  eventId: string; // Unique ID for deduplication
  event: string; // The event type, [`failed`, `transcriptionCompleted`]
  taskId: string; // The task ID
  notificationFor: NotificationFor.TRANSCRIPT;
  transcriptUrl: string; // presigned URL to access the transcript with a TTL of 60 minutes.
}

Render Notification​

If the notification is for a render task:

{
  eventId: string; // Unique ID for deduplication
  event: string; // The event type, [`failed`, `completed`]
  taskId: string; // The task ID
  notificationFor: NotificationFor.RENDER;
  transcriptUrl: string; // presigned URL to access the transcript with a TTL of 60 minutes.
  renderUrl: string; // presigned URL to access the rendered video with a TTL of 60 minutes.
}

Render Progress Notification​

If the notification is for a render task:

{
  eventId: string; // Unique ID for deduplication
  event: string; // The event type, [`failed`, `completed`]
  taskId: string; // The task ID
  notificationFor: NotificationFor.RENDER_PROGRESS;
  progress: number; // A decimal value, between 0 and 1
}

Security​

Signature Verification​

To ensure the authenticity of the webhook message, a signature is included in the headers of the POST request. This signature helps verify that the message is indeed from ZapCap and has not been tampered with. You can verify this signature using your webhook secret found here.

What is the Signature?​

The signature is a hashed representation of the payload, generated using the HMAC (Hash-based Message Authentication Code) algorithm with SHA-256. It combines your webhook secret and the payload to create a unique hash. This hash is then included in the headers of the POST request under the x-signature key.

Generating the Signature​

Here's how the signature is generated:

const generatedSignature = crypto
  .createHmac("sha256", body.webhookSecret) // Create a HMAC with SHA-256 using the webhook secret
  .update(JSON.stringify(payload)) // Payload received in the webhook notification
  .digest("hex"); // Output the HMAC as a hexadecimal string
return generatedSignature === receivedSignature; // Compare the received signature in x-signature header to the generated value

Successful Processing​

Upon successful processing of the webhook message, your endpoint should return a 200 status code within 300 ms. This indicates to the ZapCap API that the message was received and processed correctly.

Retries​

If the ZapCap API doesn't receive a 200 status code response in a timely manner, it will attempt to resend the message to the webhook endpoint up to 5 times.

Conclusion​

Webhooks provide a flexible way to get real-time updates on your video tasks. Ensure your webhook endpoint is secure, processes messages correctly, and returns the appropriate status codes to maintain efficient communication with the ZapCap API.