# Sonilo webhooks

Canonical docs: https://platform.sonilo.com/docs/webhooks
Source path: /pt/docs/webhooks

Get an HTTPS POST when an async task finishes instead of polling GET /v1/tasks/{task_id}. Supported today on POST /v1/dubbing via the callback_url form field.

## Request

- callback_url: https only, at most 2048 characters, must resolve to a public address; otherwise 422 before anything is billed.
- Polling keeps working and returns the same body.

```bash
curl -X POST https://api.sonilo.com/v1/dubbing \
  -H "Authorization: Bearer $SONILO_API_KEY" \
  -F "video_url=https://example.com/clip.mp4" \
  -F 'languages=["es"]' \
  -F "callback_url=https://example.com/webhooks/sonilo"
```

## Events

One event per task: task.succeeded or task.failed. Body: {"id": "evt_<task_id>", "type", "created_at" (ISO 8601 UTC), "data"}, where data is exactly the GET /v1/tasks/{task_id} body. For task.failed, data carries error and refunded; a failure is sent once its refund has settled, so refunded is final.

## Headers (Standard Webhooks)

- webhook-id: the event id, stable across retries; deduplicate on it.
- webhook-timestamp: unix seconds of this attempt.
- webhook-signature: space-separated `v1,<base64>` signatures; two for 24 hours after a secret rotation.
- Sonilo-Event: the event type. User-Agent: Sonilo-Webhooks/1.0.

## Verify

Use the official standardwebhooks library (https://www.standardwebhooks.com) with the whsec_ signing secret from the dashboard API keys page, on the raw request body. It rejects timestamps more than 5 minutes off.

```python
from standardwebhooks.webhooks import Webhook

event = Webhook(os.environ["SONILO_WEBHOOK_SECRET"]).verify(raw_body, headers)
```

```javascript
import { Webhook } from "standardwebhooks";

const event = new Webhook(process.env.SONILO_WEBHOOK_SECRET).verify(rawBody, headers);
```

Without a library: base64 HMAC-SHA256 of `<webhook-id>.<webhook-timestamp>.<raw body>`, keyed with the base64-decoded secret after whsec_; accept if any v1 entry matches, compared in constant time.

## Retries

- Any 2xx within 10 seconds is delivered. Anything else (other status, timeout, connection error, redirect) is retried after 1 min, 5 min, 30 min, 2 h and 6 h, then dropped.
- Delivery is at least once: deduplicate on webhook-id. Redirects are never followed.
- Respond quickly and process afterwards. Result URLs in data expire; fetch the task again for fresh ones.

## Signing secret

One per account, on the dashboard API keys page under Webhooks. After a rotation, every webhook is signed with both the new and the old secret for 24 hours. Only the newest two secrets ever sign, so rotating again within those 24 hours ends the earlier overlap.

