HeyGen idempotency keys replay within 24h; per-job callbacks are not HMAC-signed

HeyGen idempotency keys replay within 24h; per-job callbacks are not HMAC-signed

TL;DR

Always send an idempotency key (a UUID is a safe default) on HeyGen mutations so network retries never create duplicates; treat a 409 requestinprogress as still running, not as a failure. For per-job callbackurl webhooks, never trust the body on arrival: verify the connection is TLS to your endpoint and match the echoed callbackid against your pending jobs. If you need cryptographic assurance, register a webhook endpoint with a secret instead of relying on per-job callbacks.

Use this when you run into the situation in the title.

When not to use this skill: unrelated tasks. It covers only the procedure above.

Compatibility

The steps above apply to the commands named in them. This skill does not pin a version, so if a flag looks different on your machine, check your installed version's docs first.

Details

Context: Official HeyGen docs (CLI commands reference): documents two safety-critical behaviors. First, the idempotency-key flag: a client-supplied key lets you safely retry mutations; subsequent calls within 24 hours that share the key replay the original response, even if the request body differs slightly, and a retry arriving while the original is still in flight gets a 409 requestinprogress. Second, per-job callbackurl deliveries are NOT HMAC-signed; the docs say to authenticate them by verifying TLS and matching the echoed callbackid, and not to trust an unverified body. Signed payloads only go to webhook endpoints you register with a secret.

Source: Official HeyGen docs (CLI commands reference): documents two safety-critical behaviors. First, the idempotency-key flag: a client-supplied key lets you safely retry mutations; subsequent calls within 24 hours that share the key replay the original response, even if the request body differs slightly, and a retry arriving while the original is still in flight gets a 409 requestinprogress. Second, per-job callbackurl deliveries are NOT HMAC-signed; the docs say to authenticate them by verifying TLS and matching the echoed callbackid, and not to trust an unverified body. Signed payloads only go to webhook endpoints you register with a secret.

Verified resolution: Always send an idempotency key (a UUID is a safe default) on HeyGen mutations so network retries never create duplicates; treat a 409 requestinprogress as still running, not as a failure. For per-job callbackurl webhooks, never trust the body on arrival: verify the connection is TLS to your endpoint and match the echoed callbackid against your pending jobs. If you need cryptographic assurance, register a webhook endpoint with a secret instead of relying on per-job callbacks.

Source URL: https://developers.heygen.com/commands