Create an endpoint

POST{BASE_URL}/webhooks

Registers a URL to receive the events you choose, for every partner connected to you. Requires a provider key; the partner header is ignored. The response is the only endpoint read that includes the full signing secret — store it in your receiver. You can reveal it again later.

Body

urlstringrequired: An https URL that resolves only to public addresses, at most 2,048 characters, with no username, password or #fragment, and not on a blocked port. See URL requirements.
environmentstringrequired: SANDBOX or PRODUCTION, in any case. It cannot be changed later.
eventsstring[]required: The event names to send it, at least one — see Events. A repeated name is kept once. ping cannot be subscribed to.
descriptionstring | nulloptional: Your note, up to 200 characters. An empty string is stored as null.

Response

dataobjectrequired: The webhook endpoint, plus secret.
data.secretstringrequired: The signing secret, whsec_ and 43 more characters. Verify every delivery with it.

Status codes#

Status	Code	Meaning
`201`	—	Created.
`400`	—	A field is missing or invalid; `message` names it.
`400`	`invalid_events`	`events` is not a non-empty list of known event names. `details.allowed` lists them.
`400`	`event_not_subscribable`	`events` includes `ping`.
`400`	`https_required`, `private_address`, …	The URL is refused. See Refused webhook URLs.
`403`	`provider_key_required`	A partner key made the call.
`409`	`webhook_endpoint_limit_reached`	You already have 10 endpoints.
`409`	`webhook_endpoint_duplicate`	You already have an endpoint with this URL in this environment.

curl -X POST "$LOCALOY_BASE_URL/webhooks" \
  -H "Authorization: Bearer $LOCALOY_PROVIDER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/localoy",
    "environment": "PRODUCTION",
    "events": ["booking.created", "connection.updated", "connection.revoked"],
    "description": "Production receiver"
  }'

Response · 201

{
  "success": true,
  "message": "Webhook endpoint created. Store the signing secret in your receiver — every delivery, for every partner, is signed with it.",
  "data": {
    "id": "cm8wh00k0000000000000001",
    "url": "https://hooks.example.com/localoy",
    "description": "Production receiver",
    "environment": "PRODUCTION",
    "events": ["booking.created", "connection.updated", "connection.revoked"],
    "status": "ENABLED",
    "disabledAt": null,
    "disabledReason": null,
    "secretPreview": "whsec_Xq9vT0…",
    "secretRotatedAt": null,
    "lastSuccessAt": null,
    "lastFailureAt": null,
    "lastError": null,
    "consecutiveFailures": 0,
    "createdAt": "2026-09-27T09:30:00.000Z",
    "updatedAt": "2026-09-27T09:30:00.000Z",
    "secret": "whsec_Xq9vT0bLm3Rk8sYw2Ea5Nc7Pd1Gf4Hj6Kl9Mn0Qr3St"
  }
}