Skip to main content
Add your server’s URL under Webhooks in the dashboard, and NagaAI sends it a video.completed or video.failed event when a video job ends. The events are OpenAI’s: the same body, signed by the Standard Webhooks spec, so the OpenAI SDK’s webhooks.unwrap() verifies them as they are.

Receive an event

The server below checks the signature, then fetches the finished job with your API key. Set NAGA_WEBHOOK_SECRET to the signing secret the dashboard showed when you added the endpoint.
Each event arrives as a POST with a JSON body and three signature headers:
data.id is the job id that POST /v1/videos returned. The event carries no video, prompt or price. Fetch the job with GET /v1/videos/{id} to read urls, usage or error, as Video generation shows. That way a leaked event exposes nothing, and only your key reads the result.

Add an endpoint

Open Webhooks in the dashboard and choose Add endpoint. The page is in the Account group of the sidebar, and only the account’s owners and admins see it. Enter three things:
  • the URL, which must be https and reach a public server;
  • an optional description, for your own reference;
  • the events to send: video.completed, video.failed, or both.
The dashboard then shows the signing secret, which starts with whsec_. Copy it at once: NagaAI stores it encrypted and can’t show it again. If you lose it, delete the endpoint and add it again. An account can have up to 10 endpoints, and every endpoint subscribed to an event gets its own copy. An endpoint gets the events of every video job in the account, whichever API key or workspace started it. A job that fails before NagaAI returns its id gets no event, because your POST /v1/videos already received the error.

Test the endpoint

In the endpoint’s menu, Send test video.completed queues a real, signed event to that endpoint alone. Its data.id starts with video_test_ and isn’t a job, so GET /v1/videos/{id} answers 404 for it. Within a few seconds the test appears under Recent deliveries with the status your server returned. To check your verification code without a deploy, sign a sample event the way NagaAI does and pass it to unwrap(). The script below uses a throwaway secret, so it runs anywhere:
It prints video.completed video_test_0123456789abcdef. Without the OpenAI SDK, use any Standard Webhooks library: it verifies the same headers.

Retries and duplicates

Answer with any 2xx status within 10 seconds, and do the slow work after you answer. Any other status, a redirect, a timeout or a refused connection counts as a failure, and NagaAI tries again. The first retry comes 5 seconds later. Each next one waits twice as long, up to 6 hours apart. The last try comes 72 hours after the event, and then NagaAI marks the delivery failed. NagaAI never follows a redirect, so register the final URL. Every retry of an event carries the same webhook-id, the event’s id. Store the ids you’ve handled and skip one you’ve seen. A retry can arrive after your server handled the first copy, before NagaAI read its answer. The dashboard’s Recent deliveries section lists the last 50 deliveries with their state and attempts. It also shows the last answer: an HTTP status, or what happened instead, such as no answer in 10 s. Disabling an endpoint pauses its queued deliveries. They resume if you enable it again within 72 hours of their event.

Troubleshooting

The dashboard says the URL must point to a public server

NagaAI sends events only to public addresses. The host of the URL must not be or resolve to a private, loopback, link-local or other internal address. The dashboard refuses such a URL when you add it, and the gateway refuses it again on every delivery. To test from your own machine, expose the local server through a tunnel such as ngrok and register the tunnel’s https URL.

InvalidWebhookSignatureError on every event

The signature covers the body byte for byte. If your framework parsed the JSON and you pass a re-serialized copy to unwrap(), the bytes differ and the check fails. Pass the raw body, as both examples do. Check also that NAGA_WEBHOOK_SECRET is the secret of this endpoint, including the whsec_ prefix. unwrap() also rejects a webhook-timestamp more than five minutes from your server’s clock, so keep the clock in sync.

A delivery shows HTTP 404 or HTTP 405

The URL reaches your server, but no route there accepts a POST on that path. Compare the path in the endpoint with the route in your code, then send a test event again.