Skip to main content
POST
/
v1
/
webhooks
Create Webhook
curl --request POST \
  --url https://api.example.com/v1/webhooks \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "events": [
    {}
  ],
  "description": "<string>",
  "active": true
}
'
{
  "data": {
    "webhook": {
      "id": "<string>",
      "url": "<string>",
      "events": [
        {}
      ],
      "description": "<string>",
      "active": true,
      "secret": "<string>",
      "created_at": "<string>"
    }
  }
}

​
Request

​
Headers

Authorization: Bearer wbk_your_api_key_here
Content-Type: application/json
Requires an API key with the webhooks:write permission.

​
Body Parameters

​
url
string
required
HTTPS URL that will receive event deliveries. Must start with https://. URLs that resolve to private IP ranges are rejected (SSRF protection).
​
events
array
required
Array of event type strings to subscribe to. See Webhooks for the full list of 28 supported events.
​
description
string
Optional human-readable description (max 200 chars).
​
active
boolean
default:"true"
Whether the webhook should be active immediately. Set to false to register but pause deliveries.

​
Response

The secret field is returned only once — at creation time. Store it in a secure secret manager immediately. It cannot be retrieved later; if lost, delete and recreate the webhook to rotate.
​
data
object
curl -X POST https://data.leadlex.com/functions/v1/api-gateway/v1/webhooks \
  -H "Authorization: Bearer wbk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/leadlex/webhook",
    "events": ["contact.created", "deal.updated"],
    "description": "Production CRM sync",
    "active": true
  }'

​
Example Response

{
  "data": {
    "webhook": {
      "id": "7f3c4d2a-1b8e-4a9c-9d6f-2e5b8c7a1f3d",
      "url": "https://example.com/leadlex/webhook",
      "events": ["contact.created", "deal.updated"],
      "description": "Production CRM sync",
      "active": true,
      "secret": "whsec_9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f",
      "created_at": "2026-04-17T14:23:05Z"
    }
  }
}

​
Errors

StatusCodeDescription
400invalid_urlURL is not HTTPS, is malformed, or resolves to a private IP range
400invalid_eventsOne or more event names are not recognized
400missing_required_fieldurl or events is missing
401invalid_keyInvalid or expired API key
403insufficient_permissionsMissing webhooks:write permission
409duplicate_webhookA webhook with this URL already exists
429rate_limitedRate limit exceeded