Webhooks

When an asynchronous job (a video, or an image requested with Prefer: respond-async) reaches a final state, or a workflow run makes progress, GEEKIDEA sends a POST to your webhook endpoints. Synchronous calls don’t send webhooks; their result is already in the response.

Create an endpoint

Create endpoints in the dashboard under Settings → Webhooks, or with an admin key:

curl https://api.geekidea.ai/v1/organization/webhook_endpoints \
  -H "Authorization: Bearer $GEEKIDEA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhooks/geekidea", "events": ["generation.completed", "generation.failed"]}'

url must be https and publicly reachable; private and internal addresses are rejected.
project_id limits the endpoint to one project; leave it out to receive events for the whole organization.
events defaults to all events.
The response includes the signing secret (whsec_…) once. If you lose it, rotate it.

An organization can have up to 20 endpoints. You can also update, disable, delete, send a test event, rotate the secret, list deliveries and resend a delivery. See Webhooks in the API reference tab.

Events

Event	When
`generation.completed`	The job finished and was charged
`generation.failed`	The job failed and was not charged
`generation.cancelled`	The job was cancelled
`workflow.step.completed`	A workflow step succeeded
`workflow.waiting_input`	A workflow run stopped for confirmation
`workflow.budget_exceeded`	A workflow run paused because a step ran out of money (the held amount, `budget_usd`, your balance or the key’s limit)
`workflow.completed`	A workflow run succeeded
`workflow.failed`	A workflow run failed
`workflow.cancelled`	A workflow run was cancelled
`webhook.test`	You sent a test event

{
  "id": "evt_0192f1c3a7b87c3e9a4f5b6c7d8e9f01",
  "object": "event",
  "type": "generation.completed",
  "created_at": 1791425160,
  "data": { "id": "video_…", "object": "video", "status": "completed", "output": { "videos": [ … ] }, "usage": { … }, "metadata": { … } }
}

For generation.* events, data is the same generation object that GET /v1/generations/{id} returns. For workflow.waiting_input, workflow.budget_exceeded, workflow.completed, workflow.failed and workflow.cancelled, data is the run object that GET /v1/workflow_runs/{id} returns. For workflow.step.completed, data is a step event:

{
  "id": "evt_0192f1c3a7b87c3e9a4f5b6c7d8e9f02",
  "object": "event",
  "type": "workflow.step.completed",
  "created_at": 1791425260,
  "data": {
    "object": "workflow.step",
    "run_id": "run_0192f1c3a7b87c3e9a4f5b6c7d8e9f01",
    "workflow": "geekidea/drama-episode",
    "progress": 22,
    "step": { "key": "story", "status": "waiting_input", "attempt": 1, "error_code": null, "started_at": 1791425201, "finished_at": 1791425260, "confirmed_at": null }
  }
}

step is the step’s state when the event is sent; a step that stops for confirmation shows waiting_input.

Verify signatures

Webhooks are signed with Standard Webhooks, the same scheme OpenAI uses. Each request has the headers webhook-id (the event ID), webhook-timestamp and webhook-signature. Verify with a Standard Webhooks library, or with the OpenAI SDK’s webhooks.unwrap, using your whsec_ secret.

import os

from standardwebhooks import Webhook

wh = Webhook(os.environ["GEEKIDEA_WEBHOOK_SECRET"])
event = wh.verify(request.body, request.headers)  # raises if the signature is invalid

import { Webhook } from 'standardwebhooks'

const wh = new Webhook(process.env.GEEKIDEA_WEBHOOK_SECRET)
const event = wh.verify(rawBody, headers) // throws if the signature is invalid

Verify against the raw request body, and reject timestamps more than 5 minutes from now.

Delivery and retries

Respond with a 2xx within 15 seconds. Anything else counts as a failure. Redirects are not followed.
Failed deliveries are retried after 5 s, 30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h, 6 h and 8 h (about 22 hours in total), then marked dead. You can resend any delivery.
Rarely, the same event is delivered twice. Deduplicate on webhook-id.
Webhooks are notifications. The source of truth is GET /v1/generations/{id} (or GET /v1/workflow_runs/{id} for workflows), so keep a polling fallback for jobs you don’t hear about.

Get started

Generate

Workflows

Async and webhooks

Account

Create an endpoint

Events

Verify signatures

Delivery and retries

​Create an endpoint

​Events

​Verify signatures

​Delivery and retries

Create an endpoint

Events

Verify signatures

Delivery and retries