manilo.ai / developers / webhooks

Get called when a job is finished.

Instead of polling a job, register a webhook. manilo sends a signed request to your server when a translation is completed or has failed.

Setting up

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.

Events

EventSent when
job.completedA translation is finished and the result can be downloaded
job.failedA translation could not be completed. Nothing was charged

The request

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.

Verifying the signature

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.

Responding and retries

Testing

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.