Webhooks

Localoy tells your server when something happens for a connected partner — one of your items changes, a customer books, a payment settles, the partner changes your access — with a signed HTTPS POST. The envelope, signatures and retries are the ones partners get. Three things differ:

1. You manage your endpoints through the API, with your provider key. There is no portal for providers.
2. One endpoint serves every partner. Each event carries the partnerId it belongs to.
3. What you receive follows each connection — the scopes it grants, your modules and its status.

One endpoint for every partner#

{
  "id": "evt_mfz3k2a1Xq9vT0bLm3Rk",
  "event": "booking.created",
  "occurredAt": "2026-09-27T11:05:42.230Z",
  "environment": "production",
  "partnerId": "cm1partnerid000000000000001",
  "data": { "booking": { "…": "…" } }
}

Find the partner by partnerId — the ID you send as X-Localoy-Partner-Id. For a partner you no longer know, answer 2xx anyway, so the event is not retried.

Set up an endpoint#

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", "booking.updated", "booking.cancelled", "connection.updated", "connection.revoked"],
    "description": "Production receiver"
  }'

The response carries the endpoint's signing secret, starting whsec_. Store it in your receiver. You can reveal it again and rotate it later.

You can hold up to 10 endpoints, and the same URL cannot be registered twice in one environment. Every endpoint operation is in the reference.

Events#

Booking and payment events carry the same booking object partners receive, including customerName, customerPhone and customerEmail — see Booking events. Catalogue events carry the item, as in Catalogue events. The two connection.* payloads are in Connection events; only Technology Providers can subscribe to them.

Environments#

• booking.* and payment.updated go only to production endpoints: real bookings exist only in production.
• catalog.item.* go to your endpoints of the environment of the key that made the change.
• connection.* come from the partner's own actions in its Partner Portal, not from one of your keys, so they go to every endpoint subscribed to them in both environments, under one event ID. Each delivery's environment is its endpoint's.
• A test ping goes to the endpoint you tested, with partnerId null.

When nothing is delivered#

Verifying signatures#

Deliveries are signed exactly like partners' webhooks, each with its endpoint's own secret:

X-Localoy-Signature: t=1790500000,v1=5b1f0c9e4a…

v1 is the hex HMAC-SHA256 of {t}.{raw body}, keyed with the endpoint's full whsec_… secret. Follow Verifying signatures: its Node.js, PHP and Python code works unchanged. The other headers — X-Localoy-Event-Id for de-duplication among them — are listed in Receive an event.

Delivery and retries#

The policy is the one in Delivery and retries: answer 2xx within 10 seconds; a failed delivery is retried, up to 6 attempts over about five minutes; and an endpoint is disabled after 10 consecutive failed attempts. Delivery is at least once, and in no guaranteed order.

Your delivery log#

To recover after your endpoint was down:

A test works on a disabled endpoint. Enabling an endpoint resets its failure count. A replay keeps the event's ID, so a receiver that already processed the event recognises it.