Skip to main content
For every event a webhook is subscribed to, Tolk sends a POST with a JSON body to the URL of the webhook. How to create a webhook is described in the user guide.

The body

Every delivery has the same envelope:
The payloads contain counters and language codes, never texts or keys. Fetch the content through the API.

Headers

Verifying the signature

  1. Reject a timestamp that differs more than 300 seconds from your own clock.
  2. Compute the HMAC-SHA256 with the secret over the timestamp, a dot and the raw body. Do not parse and reformat the JSON first.
  3. Compare the result with X-Tolk-Signature in constant time.
In Laravel, a route in routes/web.php is behind CSRF protection. Put the webhook route in routes/api.php, or exclude it from CSRF.

Responses and retries

  • Respond with a 2xx within 5 seconds. Do the real work afterwards, for example in a queue.
  • Any other response, or no response, gets up to 5 retries with an increasing delay (10 s, 30 s, 90 s, 270 s and 810 s).
  • A delivery can arrive more than once. Use X-Tolk-Delivery to recognize duplicate deliveries.
  • Tolk does not follow redirects. Every attempt has its own timestamp and therefore its own signature.

Events and payloads

keys.synced

After a sync that created, updated, restored or archived keys.

language.completed

A target language is 100% translated. Bundled: at most one message per 5 minutes per project.

translations.updated

Translations have changed. Bundled: at most one message per 5 minutes per project. since is the start of the bundle.

import.finished

An import succeeded or failed. job is the job of GET /jobs/{jobId}. result is null if the import failed; error.code is then the code of the job.

ai_job.finished

An AI translation has finished, without costs. status is completed, failed, cancelled or budget_exceeded.

ping

The test message of Send test (Test versturen). You cannot subscribe to it.