Route a completed video
The example matches a signed video.completed event to its job and checks the result URL before delivery.
Let ngram notify your service when a video completes or fails. Verify the signature, match the video ID to the original record, and send completed files and failures to different destinations.
- Choose the scope — Set a callback for one job or subscribe to one account event type.
- Verify the request — Check the raw body, timestamp and HMAC-SHA256 signature.
- Handle a repeat — Keep the video and version IDs so retries do not duplicate customer delivery.
Three example webhook deliveries
Send a failure to the job owner
The receiver gets video.failed with error_code and error, records the failure and acknowledges receipt.
Recover after a temporary receiver outage
A receiver returns HTTP 503 on its first attempt and HTTP 204 on the retry. Match the same video and version before notifying the customer again.
How it works
From a terminal event to a customer record
Keep creation, webhook receipt and customer delivery as separate states in your application.
01
Choose a job callback or subscription
For one job, include webhook_url and webhook_secret when creating it. For persistent events, POST to /api/v1/webhooks/subscriptions with event_type and a publicly reachable HTTPS target_url. Subscribe separately to video.completed and video.failed; save each returned secret before closing the response.
02
Verify before using the payload
Use the secret for that endpoint, X-Ngram-Timestamp and the exact raw request body to verify X-Ngram-Signature. Reject an invalid signature or a timestamp more than five minutes from your server clock.
03
Record the event durably
Match video_id to the source record. Persist the event or enqueue work durably, then return a 2xx response within ten seconds. A valid duplicate that is already recorded can be acknowledged without repeating the work.
04
Route the result
For video.completed, inspect version_id and result.url before delivery. For video.failed, keep error_code and error with the job and notify the owner. A preview-only completion has no MP4 URL; read the job or export the version.
What the server exposes
What the receiver needs to handle
Keep event verification and durable receipt separate from downstream work.
Two event types
video.completed carries the delivered result and can include version_id. video.failed carries the job ID and an error code and message. Register a standing subscription for each event type needed.
Signed deliveries
Subscriptions return their signing secret only when created. For a job-specific callback, supply webhook_secret to receive signed events. Signatures cover the timestamp, a period and the raw body.
Retries without duplicate delivery
A timeout or non-2xx response triggers retry attempts. Acknowledge durable receipt promptly and make notifications or file placement idempotent in your own service.
Edits are new deliveries
An edit that produces a new version can announce video.completed again under the same video_id. Use video_id plus version_id to distinguish the new result from an earlier delivery.
Where it fits
When to react to a video event
Use a webhook for asynchronous jobs whose outcomes must reach another system. A one-off operator can read the status directly instead.
Update the correct customer record
Store the source record and video ID at creation. When a signed completion arrives, match the job, check the file, and update that customer’s record once.
Explore the workflowGive the editor a useful failure
On video.failed, keep the job ID and reason in the review queue. Resolve the cause before starting another job. There is no finished file to send.
Explore the workflowRefresh a file after a reviewed edit
When a new version completes, replace or version the existing delivery according to the customer’s workflow. A retry of the same version should not create another notification.
Explore the workflowThe rest of ngram
Explore all features What to review in the video project
A webhook carries a result or error. Use the project in ngram for creative changes before delivering its next version.
AI Visuals
When the notification arrives, inspect the visuals in the actual project if review is required.
Explore featureAI Voiceover
Check that the delivered version includes the intended narration before sending a customer notice.
See featureScript Generation
Use the stored source brief to review claims in the completed video.
See featureVideo Editing
An edited output may generate another completion event with the same video ID.
See featureMotion Graphics
Review animated diagrams in the actual file, separate from the receipt.
See featureCaptions
Confirm that subtitles appear in the file selected for downstream delivery.
See featureBrand Kit
Check the customer-facing version before the portal marks it delivered.
See featureTranslation
Track a translated project as a distinct deliverable in the customer record.
See featureChoose source material
All converters Where should the video brief come from?
Prepare the approved source before submitting the job. The webhook handles the resulting event after creation.
More ngram tools
All ngram tools Tools for a separate project edit
Use these Studio tools to prepare or revise the video when the job needs a creative change.
Create from approved materialStart from approved material
Text to Video
Create an approved draft before configuring its delivery event.
Open toolAI Avatar Video Generator
Use the presenter tool when the creative source needs to change.
Open toolAI Voice Generator
Check the narration before delivering a revised file.
Open toolAI Image Generator
Create a supporting visual for a revision that needs a new image.
Open toolReview a finished projectReview the first preview
Auto Subtitle Generator
Adjust subtitles and track the resulting updated version.
Open toolBackground Noise Remover
Treat cleanup as a project change, separate from webhook delivery.
Open toolVideo Translator
Track the alternate-language video as its own deliverable.
Open toolEye Contact AI
Use the project tool to correct presenter footage before sharing.
Open toolTrim or revise the cutFinish a project in Studio
Video Cutter
Trim footage before asking for another deliverable.
Open toolVideo Editor
Review an incorrect cut in the project rather than retrying its notification.
Open toolAdd Subtitles to Video
Check subtitles on the specific file your receiver will send.
Open toolAdd Music to Video
Review the soundtrack before distributing an edited version.
Open toolBuilt for teams
All solutions Who owns the request and result?
Assign the job to the team that can validate the source, check the correct customer destination and respond when the job needs attention.
Developer Relations
Keep a sample request beside its expected response for developer onboarding.
Customer Success
Match the right customer record with its onboarding video.
By industry
Other ways to trigger ngram
All integrations Choose the trigger or delivery mechanism
Pick the starting surface and the result-handling mechanism independently. A request to create a video and a notification about its result do different jobs.
Public APIcreate
Create the job in your own application and keep its ID with the source record.
Explore the public API
MCP ServercreateUse a compatible assistant for creative decisions and revisions in conversation.
Explore MCP
ZapiercreateStart and route a job through a managed workflow with supported trigger and action fields.
Explore Zapier
n8ncreateUse the ngram node when a team already owns conditional routing and workflow operations in n8n.
Explore n8nHow it compares
Choose how your application starts and follows a job
Webhooks Signed event | Status polling Caller reads | MCP Assistant | Zapier Workflow | |
|---|---|---|---|---|
| Who initiates | ngram on completion or failure | Your server | A person in chat | A trigger in a Zap |
| Result reference | Job and version IDs | Job and version IDs | Project or preview link | Mapped action result |
| Where it fits | Asynchronous delivery | Occasional status reads | A changing creative brief | Managed workflow routing |
| Next step | Authenticate and route the event | Read after the suggested delay | Review in conversation | Continue the configured Zap |
FAQ
Questions about webhook delivery
Use video.completed and video.failed. An account subscription accepts one event_type per subscription. A callback specified on the create request follows that particular job.
Still curious? Read the setup guide
Webhooks
Test both outcomes on your receiver
Register a receiver, verify a signature and route completed and failed events before connecting a customer destination.