Webhooks

​

Before you start

• The Webhooks entry needs to be in your sidebar. If it isn’t, webhooks aren’t enabled on this deployment — contact your team admin.
• You need an admin role in the team that will own the webhook.
• An HTTPS endpoint reachable from the public internet. http:// is not accepted.

​

Create a webhook

1. Open Webhooks in the sidebar.
2. Click Create webhook.
3. Enter:
   • URL — your endpoint. Must be https://.
   • Events — pick which events trigger delivery. See the list below.
   • Description — internal label.
4. Click Create. The dashboard shows the webhook’s signing secret. Copy it now — like credentials, it’s shown once.

​

Events

​

Payload shape

POST /your/path HTTP/1.1
Content-Type: application/json
X-Webhook-Signature-256: sha256=<hex_hmac>

{
  "event_type": "task.completed",
  "task_id": "019c65a0-aaaa-7bbb-cccc-dddddddddddd",
  "task_status": "completed",
  "task_output": {
    "storage_key": "tasks/019c65a0.../output.png",
    "image_count": 1
  },
  "task_error": "",
  "timestamp": "2026-02-16T09:00:00Z"
}

​

Verify the signature

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(body: Buffer, header: string, secret: string): boolean {
  const expected = createHmac('sha256', secret).update(body).digest('hex');
  const received = header.replace(/^sha256=/, '');
  return (
    expected.length === received.length &&
    timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(received, 'hex'))
  );
}

import hmac, hashlib

def verify(body: bytes, header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", header)

​

Acknowledge promptly

• Respond 2xx quickly. Slow responses count as failures and trigger the retry policy.
• Do the heavy work asynchronously. The handler should validate the signature, enqueue the work, and return — not block on downstream systems.

​

Retries

​

Rotate the signing secret

​

Don’t

• ❌ Trust the payload without verifying the signature.
• ❌ Block on slow work in the request handler — acknowledge first, process after.
• ❌ Expose the signing secret in client-side code. It’s a server-side secret.

​

Related

• Tasks — the events you’ll most often react to.
• Stream task events (SSE) — for per-step progress, not just terminal events.
• API reference — webhook management endpoints.