Webhooks
Don't poll. We call you. When a batch or a single recipe finishes, Scarleta sends an HTTP POST to your endpoint with the completion event. Give us the URL when you submit the work, or register addresses once and receive every event.
How you receive a webhook
You can provide the destination inline, as the webhook_url field in the API request payload. When the job reaches a terminal state, we POST the event to exactly that URL. The URL travels with the request that starts the work. You can also register addresses once, as described below.
curl -X POST https://api.scarleta.ai/v1/batch \
-H "Authorization: Bearer $SCARLETA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"recipe_id": "rec_1002_cat_vocal_stems",
"audio_urls": ["https://example.com/track-1.wav"],
"webhook_url": "https://your-app.com/hooks/scarleta"
}'Registered addresses
Register an address once with POST /v1/webhooks and it receives every batch_completed and recipe_completed event of your account, in addition to the webhook_url of a single request. An address identical to the request's webhook_url is delivered once. Each delivery is signed exactly like a webhook_url delivery, with the same retries, 10 seconds timeout and no redirects. You can register at most 5 addresses. List them with GET /v1/webhooks; deleting an address with DELETE /v1/webhooks/{id} stops future deliveries to it. Events reach a registered address at least once, on a best-effort basis: de-duplicate by batch_id plus completed_at (batches) or job_id (recipe runs).
Registering an address, deleting one, rotating the secret and revoking it each email the account owner a notice (it names the address's host, never a secret). The response carries notice_sent: it is false when no email was sent, including when the secret was already revoked, and it never means the action failed.
curl -X POST https://api.scarleta.ai/v1/webhooks \
-H "Authorization: Bearer $SCARLETA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://your-app.com/hooks/scarleta" }'See the webhooks reference for every route.
The batch_completed event
batch_completedWhen a batch finishes, we POST a JSON body with exactly these 9 fields, in this order:
| # | Field | Type | Description |
|---|---|---|---|
| 1 | event | "batch_completed" | |
| 2 | batch_id | string | The batch that ended. |
| 3 | status | "completed" | "failed" | "partial" | How the batch ended. |
| 4 | total_items | integer | Items in the batch. Allowed: -9007199254740991 to 9007199254740991. |
| 5 | completed_items | integer | Allowed: -9007199254740991 to 9007199254740991. |
| 6 | failed_items | integer | Allowed: -9007199254740991 to 9007199254740991. |
| 7 | cancelled_items | integer | Allowed: -9007199254740991 to 9007199254740991. |
| 8 | actual_total_cost | number | Tokens charged for the whole batch. |
| 9 | completed_at | number | When the batch ended, in milliseconds since the Unix epoch. |
Example payload
{
"event": "batch_completed",
"batch_id": "b1a2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
"status": "completed",
"total_items": 2,
"completed_items": 2,
"failed_items": 0,
"cancelled_items": 0,
"actual_total_cost": 40,
"completed_at": 1791333895009
}The same event is documented, with the requests that set it, in the batch reference.
Single recipes
recipe_completedA single recipe execution has its own completion counterpart, recipe_completed. It is delivered the same way, to the webhook_url you pass in the request payload and to your registered addresses, with the same delivery guarantees below. Its payload has these 9 fields:
| # | Field | Type | Description |
|---|---|---|---|
| 1 | event | "recipe_completed" | |
| 2 | job_id | string | The run that ended. |
| 3 | recipe_id | string | null | The recipe that ran; null if the run ended before the recipe was read. |
| 4 | status | "completed" | "failed" | How the run ended. |
| 5 | audio_url | string | The audio the run used. |
| 6 | num_steps | integer | Steps in the recipe. Allowed: -9007199254740991 to 9007199254740991. |
| 7 | completed_steps | integer | Steps that finished. Allowed: -9007199254740991 to 9007199254740991. |
| 8 | error | string | null | Why the run failed, or null. |
| 9 | completed_at | number | When the run ended, in milliseconds since the Unix epoch. |
Example payload
{
"event": "recipe_completed",
"job_id": "recipe_9f3a1c7e52b4",
"recipe_id": "rec_4821_mix_check",
"status": "completed",
"audio_url": "https://example.com/track-1.wav",
"num_steps": 1,
"completed_steps": 1,
"error": null,
"completed_at": 1792586348723
}See the recipes reference for the requests that set it.
Delivery guarantees
X-Scarleta-Timestamp (Unix seconds) and X-Scarleta-Signature: v1= followed by the lowercase hex HMAC-SHA256 of <timestamp>.<raw body>, keyed with your signing secret from GET /v1/webhooks/signing-secret. Reject a delivery whose timestamp is more than 300 seconds from your clock. Each attempt is signed afresh, so a retry carries a new timestamp.webhook_url you pass with a request is sent once per completion. Registered addresses are delivered at least once, on a best-effort basis. A retried batch sends a new batch_completed with the same batch_id and a new completed_at, so de-duplicate on batch_id plus completed_at (batches) or job_id (recipe runs).Verifying a delivery
Fetch your signing secret once with GET /v1/webhooks/signing-secret and keep it private. Recompute the signature over the raw request body, compare it in constant time, and reject stale timestamps. Rotate the secret any time with POST /v1/webhooks/signing-secret/rotate; for one day after a rotation each delivery also carries X-Scarleta-Signature-Previous, signed with the old secret. The sample below accepts either header: pass it your new secret, and the old one too while you are still switching over. Revoking the secret pauses all deliveries until you rotate.
const crypto = require('node:crypto');
const MAX_SKEW_SECONDS = 300;
function matches(expected, received) {
const a = Buffer.from(expected);
const b = Buffer.from(received);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// rawBody must be the exact bytes Scarleta sent, as a string, before any JSON parsing.
// secrets: your current secret, or [currentSecret, oldSecret] while you are still switching over.
function verifyScarletaWebhook(secrets, headers, rawBody, nowSeconds = Math.floor(Date.now() / 1000)) {
const timestamp = headers['x-scarleta-timestamp'];
// X-Scarleta-Signature is signed with the CURRENT secret. For one day after a rotation,
// X-Scarleta-Signature-Previous is signed with the OLD secret, so a receiver that still holds
// only the old secret keeps verifying. Accept a delivery if either header matches a secret you hold.
const received = [headers['x-scarleta-signature'], headers['x-scarleta-signature-previous']].filter(Boolean);
if (!timestamp || received.length === 0) return false;
// Reject stale or future deliveries (also rejects a non-numeric timestamp).
if (!(Math.abs(nowSeconds - Number(timestamp)) <= MAX_SKEW_SECONDS)) return false;
return [].concat(secrets).some((secret) => {
const expected = 'v1=' + crypto
.createHmac('sha256', secret)
.update(timestamp + '.' + rawBody)
.digest('hex');
return received.some((signature) => matches(expected, signature));
});
}Worked example
With this secret, timestamp and body, the sample above accepts the signature shown (when the clock is within 300 seconds of the timestamp) and rejects a body that differs by even one byte.
secret: example-signing-secret-not-real
timestamp: 1761650000
body: {"event":"batch_completed","batch_id":"0b1d6f6e-5c1a-4a53-9a38-7e3a9f4c2d10","status":"completed","total_items":2,"completed_items":2,"failed_items":0,"cancelled_items":0,"actual_total_cost":40,"completed_at":1761650000000}
X-Scarleta-Signature: v1=5baa564d8081f5ebd3dd8a85358eec77b4cc6e1c36e07fba93a9b8fb62e74f00