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. SetNAGA_WEBHOOK_SECRET to the signing secret the dashboard showed when you added the endpoint.
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
httpsand reach a public server; - an optional description, for your own reference;
- the events to send:
video.completed,video.failed, or both.
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. Itsdata.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:
video.completed video_test_0123456789abcdef. Without the OpenAI SDK, use any Standard Webhooks library: it verifies the same headers.
Retries and duplicates
Answer with any2xx 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’shttps 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.