Webhooks

A webhook is a message Etchv sends to your server when an async job finishes. Each message is signed so you can check it came from Etchv. Use webhooks to collect results without polling.

Transport

HTTPS · port 443

Delivery

Up to 10 attempts

Endpoints

10 per organization

Create an endpoint

Use Dashboard webhooks or the API. To create or change endpoints, you must be an owner or admin and use a key with webhooks:write. To view them, use webhooks:read.

curl https://api.etchv.com/webhooks \
  -H "X-API-Key: $ETCHV_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://your-app.com/webhooks/etchv"}'

1. Save the signing_secret from the 201 response. It is shown only once. The response also has id, url, enabled and created_at. The secret is separate from your API key.
2. Pass ?webhook_id=wh_… when submitting an async job. Only jobs that select this endpoint send events to it.
3. Verify each delivery, save its event ID and reply quickly.

Events

Job events report only the final outcome. A single failed attempt that is retried sends no failure event. The event, the job’s completion and the credit charge are saved together.

{
  "id": "evt_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "type": "watermark.embed.succeeded",
  "api_version": "2026-09-12",
  "created_at": "2026-09-12T14:30:00+00:00",
  "data": {
    "request_id": "req_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "status": "succeeded",
    "operation": "embed",
    "watermark_id": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
    "status_url": "/watermarks/jobs/req_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "result_url": "/watermarks/jobs/req_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef/result",
    "error_code": null
  }
}

Verify every delivery

1. Compute the signature over timestamp + "." + raw_request_body using the entire signing secret, including whsec_.
2. Reject timestamps more than 300 seconds away from your clock. Compare signatures in constant time (a comparison that takes the same time whether or not they match). Do this before parsing JSON.
3. Check that the body’s id matches the header. Save the event ID and queue your work in one step, so neither happens without the other.
4. Return 2xx, also for duplicates you already saved. Download and process files outside the handler.

import hashlib
import hmac
import time


def verify_webhook(raw_body: bytes, headers, signing_secret: str) -> bool:
    timestamp = headers.get("X-Etchv-Timestamp", "")
    signature = headers.get("X-Etchv-Signature", "")
    try:
        if abs(time.time() - int(timestamp)) > 300:
            return False
    except (ValueError, TypeError):
        return False
    expected = "v1=" + hmac.new(
        signing_secret.encode(),
        timestamp.encode() + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Delivery guarantees and retries

Expect duplicate events and events out of order. Each retry has the same event ID and JSON body, with a new timestamp and signature. The body shows the job at the time of the event, not its current status.

Inspect and redeliver

The dashboard shows each delivery’s status, payload and attempts. The API list returns data and next_cursor. Pass next_cursor as after to get the next page. Records last 30 days, and the last 30 attempts are kept. Your server’s response bodies are not saved.

Customer storage delivery events

When an async embed sets both webhook_id and storage_destination_id, Etchv also sends storage.delivery.succeeded or storage.delivery.failed after the upload to your bucket finishes.

Storage data contains delivery_id, asset_id, request_id, destination_id, status, error_code, uri and public_url (null for private storage). Verify the signature and skip duplicates as usual, and do not assume events arrive in order. A manual upload retry creates a new final event. See storage.