Webhooks

Account signing secret

Create the signing secret in the dashboard before adding a webhook. It is displayed once and stored encrypted by AlefBot

Delivery contract

Provide a public HTTPS endpoint when creating a transcription. The event body and headers are documented as a callback in the API reference

{
  "event": "transcription.completed",
  "event_id": "evt_...",
  "job_id": "job_...",
  "status": "completed",
  "created_at": "2026-08-14T12:00:00Z",
  "links": {
    "self": "https://alef-bot.top/api/v1/transcriptions/job_...",
    "artifact": "https://alef-bot.top/api/v1/transcriptions/job_.../artifact"
  }
}

• Each request includes X-AlefBot-Event, X-AlefBot-Event-ID, X-AlefBot-Timestamp and X-AlefBot-Signature
• Webhook tests send X-AlefBot-Event: webhook.test and a body containing test_mode: true; the precise schema is the test operation’s callback in the API reference
• Verify the signature against the raw request body before parsing JSON
• Reject old timestamps and compare signatures in constant time
• Return 2xx quickly and process the event asynchronously
• Delivery is at least once; deduplicate using event_id because delivery may be repeated
• Event order is not guaranteed
• AlefBot makes up to 5 attempts over about three hours for network failures, 408, 425, 429 and 5xx
• The target must be public HTTPS on port 443, without redirects

Test before launch

Use POST /webhooks/test to check DNS, TLS, network policy, signature verification and response time without creating a transcription