Async and batch requests deliver results to your webhook URL. Matil sends a POST request with the result payload when processing completes.
Configuration
Include a webhook object in your request:
{
"webhook": {
"url": "https://your-server.com/webhook",
"secret": "your-webhook-secret"
}
}
Signature verification
Every webhook includes a X-Matil-Signature header:
X-Matil-Signature: t=1234567890,v1=abc123...
import hmac
import hashlib
import time
def verify_webhook(payload: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
timestamp = parts["t"]
signature = parts["v1"]
signed_payload = f"{timestamp}.{payload.decode()}"
expected = hmac.new(
secret.encode(),
signed_payload.encode(),
hashlib.sha256
).hexdigest()
if not hmac.compare_digest(signature, expected):
return False
if abs(time.time() - int(timestamp)) > 300:
return False
return True
Always verify webhook signatures. Without verification, anyone could send fake payloads to your endpoint.
Retry behavior
If your endpoint doesn’t respond with a 2xx status, Matil retries up to 3 times with exponential backoff.
Events
| Event | Trigger |
|---|
structurer.completed | Async processing succeeded. |
structurer.failed | Async processing failed. |
batch.item.completed | A batch item finished (incremental mode). |
batch.completed | The entire batch finished. |
batch.failed | The entire batch failed. |
