Ideogram Webhook Verification and Reconciliation

Overview

Accept Ideogram asynchronous completion only after cryptographic verification and idempotent reconciliation. Use the raw request body, bind all signed headers, acknowledge quickly, and retain polling as a recovery path because delivery is not guaranteed.

Prerequisites

• A public HTTPS receiver, raw-body access, durable event store, queue, and clock.
• The submitted generation_id, destination object policy, and polling reconciler.
• Local Ed25519 fixtures for valid, invalid, stale, duplicate, and rotated-key deliveries.

Current Contract

Async requests can include a webhook URL and return generation_id. Ideogram signs callbacks with Ed25519 and publishes keys at https://api.ideogram.ai/v1/.well-known/jwks.json. Signed headers identify generation, user, timestamp, key, and signature. Deliveries may duplicate, retries are limited, and polling remains necessary.

Authentication

Webhook trust comes from signature verification, not a shared API key in the callback. Normal polling uses server-side IDEOGRAM_API_KEY in the Api-Key header; never expose it to the receiver request.