Skip to main content

Add a webhook

A webhook sends an HTTP POST to your server when a render completes or fails, so your application can react without repeatedly checking its status.

When to use it​

Use a registered webhook for ongoing render notifications to an application or automation. For a single render request, see per-request callbacks.

Before you begin​

  • Prepare a public HTTPS endpoint that accepts JSON POST requests and returns a 2xx response within 10 seconds.
  • Implement signature verification in your receiver.
  • Check the endpoint allowance displayed on Webhooks. Registered endpoints count toward your plan's limit even when disabled.

Register an endpoint​

Location: Dashboard → Webhooks.

  1. Select Webhooks in the sidebar, or open Webhooks.
  2. Click Add webhook.
  3. Enter Endpoint URL, for example https://example.com/hooks/zvid, using your own receiver's URL.
  4. Optionally enter Description to identify the integration.
  5. Under Events, select one or both options: Render completed (render.completed) and Render failed (render.failed). Both are selected initially.
  6. Click Add webhook.
  7. In Webhook Created, click Copy secret, save the signing secret in your receiver's configuration, then click Done.

What happens next​

Your endpoint appears with its URL, description, status, and selected events. It is active immediately. Use Send test to check the connection, following Test and manage webhook deliveries.

You can view the signing secret again

Click Signing secret on the endpoint card, then Copy secret in the dialog. Keep this value private. It is different from an API key.

Important notes​

  • Registered endpoint deliveries include an X-Zvid-Signature header. One-off webhookUrl callbacks are unsigned; do not apply the same signature assumptions to both.
  • The dashboard creates endpoints and controls their status. To edit an existing URL, description, or event selection, use the Update webhook endpoint API.
  • The receiver must use a public address. Localhost, private-network destinations, and redirects are not accepted for delivery.

Troubleshooting​

Add webhook is disabled​

Cause: You have reached the endpoint allowance shown at the top of the page.

Solution: Select Upgrade to add more, or delete an endpoint you no longer need. Disabling an endpoint does not free a slot.

The endpoint cannot be created​

Solution: Check the HTTPS URL and select at least one event. Confirm that your destination is publicly accessible. If creation continues to fail, review your plan usage before trying again.