Instead of polling a job, register a webhook. manilo sends a signed request to your server when a translation is completed or has failed.
Add the address in the manilo app under API access, section Webhooks. The signing secret (it starts with whsec_) is shown once, right after you add the address. The Test button sends an example event, so you can check your endpoint before a real job runs.
https and be reachable from the internet.| Event | Sent when |
|---|---|
job.completed | A translation is finished and the result can be downloaded |
job.failed | A translation could not be completed. Nothing was charged |
A delivery is a POST with a JSON body. The event type is also in the Manilo-Event header, and Manilo-Delivery carries the unique ID of the delivery.
{
"id": "evt_5f1c0c8e9a3b4d7e8f2a1b6c9d0e4f71",
"type": "job.completed",
"created_at": "2027-01-15T10:21:07.412345+00:00",
"data": {
"job_id": "9a9d140b-c15a-4bc5-9871-5c46a48ba004",
"status": "completed",
"filename": "catalogue-2027.idml",
"source_language": "de",
"target_languages": ["en-gb", "fr"],
"cost": 58.4,
"currency": "EUR",
"error_message": null,
"test_mode": false,
"source": "api"
}
}
Fetch the result with GET /jobs/{job_id}/download, as described in the quickstart. The payload contains no download link, so a leaked webhook request does not expose your files.
Every request carries a Manilo-Signature header with a timestamp and a signature:
Manilo-Signature: t=1800000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
The signature is the HMAC-SHA256 of the timestamp, a dot and the raw request body, keyed with your signing secret. Compute it yourself and compare. Also reject requests whose timestamp is more than a few minutes old, so a recorded request cannot be replayed.
import hashlib, hmac, time
def is_from_manilo(secret: str, signature_header: str, raw_body: bytes) -> bool:
parts = dict(item.split("=", 1) for item in signature_header.split(","))
timestamp = int(parts["t"])
if abs(time.time() - timestamp) > 300:
return False
message = str(timestamp).encode() + b"." + raw_body
expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])
Use the raw bytes of the body, exactly as received. Parsing the JSON and serialising it again changes the bytes and breaks the signature.
2xx status within 10 seconds. Do slow work after you have answered.2xx, manilo tries again after 5 seconds and once more after another 30 seconds. After three attempts the delivery is dropped.id to ignore duplicates.Jobs started with a sandbox key send the same events with test_mode: true. That lets you test the whole chain without paying for a translation.