Getting Started

Webhooks let your integration receive event data from Loyale without continuously polling the API. When a subscribed event occurs, Loyale sends the topic-specific JSON payload to every matching endpoint registered for that scheme.

How webhook delivery works

1. Choose the topics your integration needs.
2. Expose a publicly reachable HTTPS endpoint.
3. Subscribe the endpoint to each topic.
4. Accept the JSON request body and durably record or process it.
5. Return any HTTP status in the 200–299 range. Other responses and connection failures enter the retry flow.

Receiver checklist

• Accept HTTP POST requests with an application/json body.
• Return a 2xx response as soon as the event has been accepted. The response body is ignored.
• Make processing idempotent. A failed delivery can be attempted again, so the same payload may be received more than once.
• Do not rely on delivery order when processing independent events.
• Validate the payload using the model documented on its topic page.
• Use HTTPS. The current delivery request does not include a webhook-signature header.

Preventing update loops

An API change made by your integration can itself trigger a webhook. Where populated, createdBy and updatedBy identify the actor responsible for the change. The value may be an administrator email, System, or null depending on the operation.

Use those audit fields as one signal, but make your integration idempotent rather than relying on them alone. A common pattern is to record the resource ID and update timestamp before writing the corresponding change back to Loyale.

Date and time values

Webhook timestamps are emitted as UTC date-time values. Parse them as timezone-aware values and retain the UTC offset.

Next steps

• Configure subscriptions
• Review every topic and payload
• Understand retries and delivery logs