Skip to main content
POST
Create Webhook

Request

url
string
required
The HTTPS URL to deliver events to. Must use https:// in production. Subject to SSRF validation — private IPs, cloud metadata endpoints, and non-HTTP schemes are blocked.
event_types
string[]
required
Array of event types to subscribe to. Use "*" for all events, or specific types like "completion.created".Valid types: completion.created, job.completed, job.failed, workflow.completed, workflow.failed, skill.installed, skill.uninstalled, skill.submitted, skill.approved, skill.rejected, skill.suspended, connector.created, connector.status_changed, credits.low, key.created, key.revoked, *
secret
string
Optional custom signing secret (16–256 chars). If omitted, a cryptographically random 32-byte hex secret is generated.
description
string
Optional description for the webhook (max 256 chars).

Response

id
string
The webhook’s unique UUID.
url
string
The registered endpoint URL.
event_types
string[]
Subscribed event types.
enabled
boolean
Always true on creation.
signing_secret
string
The HMAC-SHA256 signing secret. Shown once — save it immediately. Used to verify webhook signatures on your server.
created_at
string
ISO 8601 timestamp.

Authentication

Requires an org-scoped API key with completions scope.

Example

Response

Limits

  • A per-organization cap on active webhooks applies. If you need more, contact support.
  • URL must pass SSRF validation (no private IPs, no cloud metadata endpoints).
  • HTTPS required in production.

Signature Verification

Every delivery includes three headers for verification:
Verify by computing HMAC-SHA256(signing_secret, timestamp + "." + raw_body) and comparing to the signature. Reject if the timestamp drifts more than 5 minutes from your clock.