> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolk.every-day.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Let Tolk tell another service that something has changed.

With a webhook, Tolk sends a signed message to a URL as soon as something changes in the project, for example when a language is fully translated. A GitHub Action can then open a pull request with the new translations automatically. Only managers manage webhooks, under **Settings › Webhooks** (*Instellingen › Webhooks*).

## Adding a webhook

<Steps>
  <Step title="URL">
    Click **Add webhook** (*Webhook toevoegen*) and enter the URL that Tolk sends a `POST` to. Only `https` addresses on the public internet are allowed, on port 443 or 8443. Tolk does not follow redirects.
  </Step>

  <Step title="Choose events">
    Choose the events for which Tolk sends a message (see below).
  </Step>

  <Step title="Store the secret">
    Tolk shows the webhook's secret **once**. Store it at the receiver right away: the receiver uses it to check that the message really comes from Tolk.
  </Step>
</Steps>

## Events

| Event | When |
| - | - |
| `keys.synced` | After a push with new or changed keys |
| `language.completed` | A language is 100% translated. Like `translations.updated`, at most one message per 5 minutes per project |
| `translations.updated` | Translations have changed. At most one message per 5 minutes per project |
| `ai_job.finished` | An AI translation is done |
| `import.finished` | An import is done |

The messages contain counts and language codes, never texts or keys. The receiver fetches the content itself through the API. The payloads and how to verify the signature are described under [Webhooks for developers](/developers/webhooks).

## Managing and checking

From a webhook's menu:

| Action | Explanation |
| - | - |
| **Send test** (*Test versturen*) | Sends a `ping` message, to see whether the receiver is reachable |
| **Delivery log** (*Leveringslog*) | The last 50 attempts, newest first, with status code, duration, error message, response and payload |
| **Edit** (*Bewerken*) | URL, events and **Active** (*Actief*) on or off. An inactive webhook receives no messages |
| **Rotate secret** (*Geheim roteren*) | Creates a new secret. The old one stops working immediately: update it at the receiver right away |
| **Delete** (*Verwijderen*) | The webhook and its delivery log are removed |

The status in the table is **Active**, **Failing** (*Fout*; the last delivery failed) or **Inactive** (*Inactief*).

## When a delivery fails

If the receiver does not answer with a `2xx` within 5 seconds, Tolk tries 5 more times, with an increasing wait in between (about 20 minutes in total). The delivery log shows what happened on each attempt. Tolk blocks a URL that points to an internal or private network; that attempt is shown as **Blocked** (*Geblokkeerd*) in the log.

A project has at most 10 webhooks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.