# Webhooks

> Let a build, a cache or a Slack channel know when a translation is ready or a sync added keys.

Canonical: https://docs.lionrapid.com/developers/webhooks/

A continuous project can notify your own service, or a Slack channel, when something happened to its translations. You set the endpoints up in the project hub’s **Integration** tab, on the **Notifications** card: pick **Slack** or **My own service**, paste the URL, and optionally narrow the endpoint to the namespaces it should hear about.

## The two events

| Event                 | Fires                               | Payload                                                                        |
| --------------------- | ----------------------------------- | ------------------------------------------------------------------------------ |
| `translation.ready`   | Once per row a person marks ready   | `locale`, `namespace`, `key`                                                   |
| `translations.synced` | Once per sync batch that added keys | `source_locale`, `keys_added`, `keys_updated`, `auto_translated`, `namespaces` |

`translation.ready` is the one to build on: it names the exact row that is now deliverable, so a build can pull that namespace, a cache can purge that page, or a channel can tell the reviewer the row is live. `translations.synced` tells you new source text arrived; its counts are for the whole batch, and `namespaces` is a list because one push can touch several.

## Format

- **My own service** receives JSON, signed:

  ```json
  {
    "id": "0193b6f2-6a51-7c2e-9d41-2f8e4c1a7b30",
    "type": "translation.ready",
    "payload": { "locale": "es", "namespace": "app", "key": "checkout.title" },
    "timestamp": "2026-10-28T09:14:03.120000+00:00"
  }
  ```

  Every request carries an `X-LionRapid-Signature` header: the HMAC-SHA256 of the request body, hex-encoded, keyed with the endpoint’s secret. The secret is shown once when you create the endpoint and can be rotated from the card; the new one is shown once again. Compute the HMAC over the raw bytes you received, before parsing, and compare it to the header with a constant-time comparison.

  The signature covers the whole body, `id` and `timestamp` included, so once it checks out you can trust both:

  - **Refuse an old message:** one whose `timestamp` is more than 5 minutes old.
  - **Refuse a repeat:** one whose `id` you have already handled. The `id` names the event, and is the same for every endpoint the event goes to.

  Each request also carries `X-LionRapid-Delivery`, a fresh id for that one delivery: quote it when you ask us about a message.

  **Rotating the secret without dropping a message.** For 24 hours after you rotate, every request also carries `X-LionRapid-Signature-Previous`, signed with the old secret. Accept either signature while you switch your service over, then only the new one. If you rotated because the old secret leaked, stop accepting it at once.

- **Slack** receives a ready-made message for the channel’s incoming-webhook URL. The URL is the credential, so a Slack endpoint has no secret and no signature.

## Delivery

Delivery is best-effort and once: each event is posted to each subscribed endpoint a single time. If your endpoint is down, times out or answers with an error, the event is not retried, so treat a webhook as a nudge and read the state from the API (or run `lionrapid validate`) rather than as the record of what happened. The card shows the last delivery outcome and a failing streak per endpoint, so a dead URL is visible without reading logs.

## Namespace filter

An endpoint with no namespaces hears about every namespace. Give it a list and it receives only the events whose payload names one of them: `translation.ready` by its `namespace`, `translations.synced` by any entry in its `namespaces`. The counts in a `translations.synced` payload stay batch-wide even when the endpoint matched on one namespace.
