# Webhooks

## Configure a signing secret

Create and save a callback signing secret in [developer settings](/settings/developer). For any published image or video model, send a top-level `callBackUrl` to `POST /api/v1/jobs/createTask`. You can also use `callbackUrl`. If you send both, they must match. Use a public HTTPS endpoint on port 443. The REST compatibility endpoint also accepts other public HTTP(S) ports. Delivery revalidates the destination, blocks private networks, and does not follow redirects.

```json
{
  "model": "gpt-image-2.6",
  "inputs": { "prompt": "A ceramic cup on a wooden desk" },
  "callBackUrl": "https://hooks.example.com/i2v/completed"
}
```

## Handle the terminal result

Success, failure, and cancellation before dispatch all send `task.completed`. Match `data.taskId` to your submission and read `data.status` and `data.lifecycle.phase` for the outcome. The event envelope can contain `code: 200` for a failed generation.

| Outcome | What to read |
| --- | --- |
| `success` | Download the result from `data.output[].url`. |
| `fail` | Inspect `data.error` and `data.billing`. A `cancelled` phase means the task was cancelled. |

Keep querying `recordInfo` for pending or reconciling tasks. Callbacks are sent when the task reaches a terminal state.

If submission returns HTTP `503` with `reason: "callback_dns_unavailable"`, retry the same body with the original `Idempotency-Key` after the callback hostname resolves again.

## Verify the event

Read these headers before parsing the request body.

| Header | Purpose |
| --- | --- |
| `X-I2V-Signature` | Versioned signature, using `v1` |
| `X-I2V-Timestamp` | Timestamp included in the signed payload |
| `X-I2V-Key-ID` | Signing key version |
| `X-I2V-Event-ID` | Stable event ID for deduplication |

Compute hexadecimal HMAC-SHA256 using your signing secret and the exact message `timestamp + '.' + raw request body`. Compare the signature with a constant-time comparison. Reject timestamps outside your application's freshness window. Store processed event IDs to handle redelivery idempotently.

## Acknowledge delivery

Return HTTP `2xx` after accepting the event. Timeouts can cause redelivery even when the event was processed. Callbacks have up to eight automatic delivery attempts with bounded exponential delay. Exhausted deliveries remain visible in the developer console for manual redelivery.

Callback delivery runs independently of task settlement. Read the final task state with [recordInfo](/docs/api) when reconciling a delivery problem. During key rotation, retain the previous key until pending deliveries finish.