HeyGen avatar_video.success vs Sume job.completed: fields to keep

HeyGen's avatar_video.success payload lists video_id, url, gif_download_url, video_page_url, video_share_page_url, folder_id and callback_id. Sume's job.completed payload is smaller and job-shaped: event, request_id, job_id, status and a payload.artifacts array whose entries carry id, url, type and content_type. In both cases the one field to store is the identifier you can use to read the resource again.

HeyGen's field list is from Webhook Events, and its create fields from the Digital Twin page, both read 2026-10-10. Sume's shape is from Webhooks.

Field by field

Use the table to decide what your database row needs.

The Sume fields an avatar integration really needs

The webhook is a notification. The richer avatar fields live on the result and on the avatar-video resource. For an Avatar 1.0 clip, the primary video_url is the clean final MP4, and the result can also include public-safe preview fields such as preview_image_url and scene_previews. If you turned on inline captions and that stage failed, the job can still succeed with captions.status=failed and a clean video.

So the receiver for a job.completed event should do three things: verify the signature, record job_id and the artifact URL, and then read GET /v1/avatar-videos/{id} or the job result for anything else. The avatar-video resource is also what lists your clips later, so you can find a clip even if you lost the event.

Tag requests with your own key

HeyGen's event page says callback_id echoes the value passed at creation, but its Digital Twin create page, read the same day, says callback_id is not a valid field there and points to callback_url. Check the live reference before you rely on a tag; I am only reporting the two pages as read.

On Sume, the tag is the idempotency key. Send Idempotency-Key on a paid create, and every job object returns it as idempotency_key, so build the key from something you can join on, such as an order id and a scene number. A retry with the same key and body returns the original job, and the same key with a different body returns 409 idempotency_conflict, whose details name the job that already holds it.

A minimal row design

• job_id: the primary key, and the key you deduplicate deliveries on.
• idempotency_key: your join key back to the order or script.
• avatar_handle and quality: what you asked for, so a cost review can reproduce the price.
• status: updated by the event or by a poll, whichever arrives first.
• video_url: copied into your own storage at the time you verify the event.

Before you trust the event

A success event is only useful if it is genuine and new. Verify the signature first, using the raw body: HeyGen specifies a hex HMAC-SHA256 digest in a signature header, and Sume signs <timestamp>.<raw_body> and sends it as sume-v1=<hex>. Then check that you have not already processed the same id, because both vendors can deliver an event more than once.

Finally, check that the media is what you asked for before it goes anywhere public. Sume's result can include preview_image_url and scene_previews, and watching the clip against the script you approved catches a rendering surprise before a viewer does. That review step is the point of a rendered clip.