Skip to content

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.

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.

  • My own service receives JSON, signed:

    {
    "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 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.

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.