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:Headers
Verifying the signature
- Reject a timestamp that differs more than 300 seconds from your own clock.
- Compute the HMAC-SHA256 with the secret over the timestamp, a dot and the raw body. Do not parse and reformat the JSON first.
- Compare the result with
X-Tolk-Signaturein 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
2xxwithin 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-Deliveryto 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.