# Webhooks

Receive completion events safely and test delivery before production

Canonical: https://alef-bot.top/en/developers/guides/webhooks

Updated: 2026-08-14

## Account signing secret

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

> **Rotate the secret.** Rotation replaces the secret immediately. Update the receiver before continuing webhook traffic

## 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

### JSON

```json
{
  "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

## Machine-readable sources

- [OpenAPI JSON](https://alef-bot.top/api/v1/openapi.json)

- [OpenAPI YAML](https://alef-bot.top/api/v1/openapi.yaml)

- [Arazzo workflow](https://alef-bot.top/api/v1/workflows/transcribe.arazzo.yaml)