How do I get a notice when my data changes with a webhook?

Send signed notices about changes to your software.

Updated November 11, 2026

Have Alori send your software a signed notice when selected data changes.

You need an HTTPS address in your software that accepts POST requests. An admin can add the webhook in Alori; to use the API instead, first make a Full access API key.

Open Connectors, choose API, and click Add a webhook under Webhooks.
Enter your HTTPS address in Address that receives them, choose the changes under When, and click Add webhook.
Copy the signing secret and store it privately. It is shown only once.
To add one with your Full access key instead, send this request. Replace YOUR_KEY and the example address. url is a string containing an HTTPS address; events is a nonempty array of event-name strings.
```
curl -X POST https://api.alori.dev/v1/webhooks \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.northwind.example/alori","events":["customer.created","deal.updated"]}'
```
HTTP 201 returns the webhook ID and its one-time secret:
```
{"id":"WEBHOOK_ID","secret":"YOUR_SIGNING_SECRET"}
```
Choose from customer.created, customer.updated, customer.deleted, deal.created, deal.updated, deal.deleted, booking.created, booking.updated, booking.cancelled, booking.deleted, note.created, and message.received.
In your receiver, check the signature before trusting the notice. Alori sends a POST to your address with Alori-Event and Alori-Signature: t=…,v1=…. Read the raw body without changing it. Compute HMAC-SHA256 with the signing secret over the exact bytes <t>.<raw body>, then compare its hexadecimal result with v1 using a constant-time comparison. Reject a timestamp more than five minutes old and reject missing or invalid signatures.
A change arrives as JSON like this:
```
{
  "id": "evt_example_customer_updated",
  "event": "customer.updated",
  "occurredAt": "2026-10-20T14:13:20.000Z",
  "recordId": "CUSTOMER_ID",
  "changedFields": ["name"],
  "source": "alori",
  "data": {"id": "CUSTOMER_ID", "name": "Northwind Studio"}
}
```
id, event, occurredAt, recordId and source are strings. data is a record object or null; changedFields, when present, is an array of strings. externalId and apiKeyId are optional strings. source is api for an API change and alori otherwise. The ID stays the same on retries, so skip an ID you have already handled.
On the webhook's row, click Send test to send a signed test event. Your receiver should answer with a 2xx status within 10 seconds. Redirects count as failures.
You can also queue a test with the webhook ID and Full access key:
```
curl -X POST https://api.alori.dev/v1/webhooks/WEBHOOK_ID/test \
  -H "Authorization: Bearer YOUR_KEY"
```
```
{"ok":true}
```

Alori retries failed deliveries after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours. After 20 failed deliveries in a row, the webhook pauses and the page shows the last error. There can be up to 10 webhooks per app and 120 API requests per minute per key.

An API error has an error object with code and message. HTTP 400 means the address or events are invalid; 401 means the key is missing, wrong or revoked; 403 means it isn't Full access; 404 means the webhook wasn't found; 409 can mean the 10-webhook limit; and 429 means the key has sent too many requests.