# Webhooks

Recevez les événements de fin en sécurité et testez la livraison avant la production

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

Updated: 2026-08-14

## Secret de signature du compte

Créez le secret de signature dans le tableau de bord avant d’ajouter un webhook. Il est affiché une fois et stocké chiffré par AlefBot

> **Remplacer le secret.** Le remplacement prend effet immédiatement. Mettez à jour le destinataire avant de poursuivre le trafic Webhook

## Contrat de livraison

Fournissez un endpoint HTTPS public lors de la création. Le corps et les en-têtes de l’événement sont documentés comme callback dans la référence API

### 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"
  }
}
```

- Chaque requête contient X-AlefBot-Event, X-AlefBot-Event-ID, X-AlefBot-Timestamp et X-AlefBot-Signature
- Les tests envoient X-AlefBot-Event: webhook.test et un corps contenant test_mode: true ; le schéma exact figure dans le callback de l’opération de test
- Vérifiez la signature sur le corps brut avant de décoder le JSON
- Refusez les horodatages anciens et comparez les signatures en temps constant
- Renvoyez rapidement 2xx et traitez l’événement de manière asynchrone
- La livraison est au moins une fois ; dédupliquez avec event_id car elle peut se répéter
- L’ordre des événements n’est pas garanti
- AlefBot effectue jusqu’à 5 tentatives sur environ trois heures pour les échecs réseau, 408, 425, 429 et 5xx
- La cible doit être HTTPS publique sur le port 443, sans redirection

## Tester avant l’activation

Utilisez POST /webhooks/test pour vérifier DNS, TLS, règles réseau, signatures et temps de réponse sans créer de 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)