HeyGen avatar_video.fail has no fields: what Sume sends on failure

On HeyGen, the avatar_video.fail webhook is documented as a signal, not a report: its page does not list payload fields for it and says to fetch the authoritative state from the API. On Sume, a failed job webhook is more self-contained: job.failed arrives with status: "ERROR" and an error object, and the same error is readable from the job record.

HeyGen's wording is on Webhook Events and its failure field on the Digital Twin page, both read 2026-10-10. Sume's behavior is on Webhooks and Jobs and results.

What each side tells you

The cells below only state what the pages say.

Write one handler for both shapes

HeyGen also lets you re-fetch the video, and its pages say the response URLs are presigned with expiry windows. Whatever you store from a success path, store the video id so the read can be repeated.

Treat every failure webhook as a trigger to read state, then act on what you read. For HeyGen that read is the video resource. For Sume it is GET /v1/jobs/{id}, which holds the public error. A handler built this way works even if a vendor adds or removes payload fields later.

The extra Sume status matters. A canceled job is terminal and produces no output, and Sume sends job.canceled for it. If you only branch on failed, a canceled avatar render will look like a missing delivery.

What to do on a Sume avatar failure

Read the error before you resubmit. The errors page separates refusals that prove no work was done, such as validation, authorization or balance, from a 5xx, which never proves that. Resubmitting a paid avatar video on a hunch can bill twice, so send the original Idempotency-Key on any retry of the submit: a retry with the same key and payload returns the original job with idempotency_hit: true.

For a validation failure on the script, remember the avatar rules: the estimated duration must fall in 4 to 60 seconds, and Avatar 1.0 is English-only. Fix the input, then submit a new request with a new key, since a changed payload under the old key returns 409 idempotency_conflict.

Debug with the events timeline

If a webhook never arrived, do not guess. GET /v1/jobs/{id}/events lists job.created, job.queued, job.started, generation.submitted, the terminal event and webhook.delivery, so you can see whether the job finished and whether delivery was attempted. Public events do not expose raw provider task ids or URLs.

A sensible log line for each failed avatar job is the job_id, the idempotency_key (returned on every job object, so it doubles as the label you join on), the error code, and the quality tier you asked for. That is enough to tell a bad script from an outage without opening the dashboard.

Pair that with the redeliver action, POST /v1/jobs/{job_id}/webhook/redeliver, which re-sends the real terminal event with a fresh timestamp and signature. It is the right tool once you have fixed the receiver, and it is not the same as Send test, which posts a dummy payload to a URL you type.