Documentation développeur

Webhooks

Les webhooks sont des notifications signées indiquant qu’une note a changé. Récupérez son contenu à jour via la REST API.

Événements webhook

Événement	Se déclenche quand
note.ended	Une session d'enregistrement s'est terminée et sa transcription finale est récupérable. Se déclenche une fois par session d'enregistrement — une note comportant plusieurs sessions l'émet plusieurs fois.
note.summary.generated	La génération d'un résumé est terminée et le résumé est récupérable.
note.updated	Des champs visibles de l'extérieur (titre, contenu) ont changé après la fin de la note. Événement soumis à un debounce — des modifications rapprochées sont fusionnées en un seul événement.
note.deleted	La note a été supprimée (data.reason: "deleted") ou est sortie du périmètre de visibilité de vos identifiants (data.reason: "access_lost").

Il existe également deux événements de service : endpoint.verification (envoyé à la création et à chaque changement d'URL ; répondez par un 2xx pour activer l'endpoint) et endpoint.test (envoyé lorsque vous cliquez sur « Envoyer un test » dans la console ou que vous appelez l'API de test).

Corps de la requête

Les webhooks sont des notifications légères : ils transportent des identifiants et des statuts, jamais le contenu des transcriptions ou des résumés. Récupérez le contenu via la REST API à l'aide du note_id.

JSON

{
  "event_id": "5f8c0a5e-...",
  "event_type": "note.ended",
  "occurred_at": "2026-08-12T05:20:00Z",
  "data": {
    "note_id": "note_abc123",
    "recording_session_id": "rec_456",
    "revision": 7,
    "transcript_status": "ready",
    "summary_status": "pending"
  }
}

Vérifier les signatures

Les livraisons sont signées conformément à la spécification Standard Webhooks, avec le secret whsec_... émis à la création de l'endpoint :

HTTP

POST /webhooks/alt HTTP/1.1
Content-Type: application/json
webhook-id: 5f8c0a5e-...
webhook-timestamp: 1765515600
webhook-signature: v1,K5oZfzN95Z9UVu1EsPQmSmZQGGVfCM0jaZ0lPI4dvLU=

signature

signed_content = "{webhook-id}.{webhook-timestamp}.{raw request body}"
signature     = base64( HMAC-SHA256( base64url_decode(secret_after_whsec_), signed_content ) )

Vérifiez la signature sur le corps brut de la requête — ne re-sérialisez pas le JSON.
Comparez les signatures avec une comparaison à temps constant.
Rejetez les horodatages trop anciens (nous recommandons une tolérance de ±5 minutes) afin de prévenir les attaques par rejeu.
Rejetez par un 4xx toute requête dont la signature ne correspond pas. Code de récepteur fonctionnel : étape 4 du démarrage rapide.

Échecs de livraison et réessais

Répondez par un 2xx en moins de 10 secondes. Toute autre réponse est comptée comme un échec. Accusez réception d'abord, traitez ensuite de façon asynchrone.
Les livraisons en échec sont réessayées avec un backoff croissant (30 s → 5 min → 30 min → 2 h → 12 h → 12 h, 7 tentatives au maximum).
Un endpoint qui enchaîne les échecs de livraison est automatiquement désactivé.
Les redirections ne sont pas suivies ; l'URL du webhook doit répondre directement en HTTPS.

Gérer les événements en double

La livraison est at-least-once : un même événement peut arriver plusieurs fois (réessais, renvois depuis la console). Conservez brièvement la trace des event_id déjà traités et ignorez les doublons.

Gérer les événements dans le désordre

Les événements peuvent arriver dans le désordre (réessais, livraisons en parallèle). Ne supposez pas que le dernier arrivé reflète l'état le plus récent. Chaque changement visible de l'extérieur incrémente la revision de la note (attribuée par le serveur, monotone) : mémorisez la révision appliquée pour chaque note et ignorez tout ce dont la révision est inférieure ou égale. En cas de doute, récupérez de nouveau la note via la REST API — elle renvoie toujours la révision courante.

Vérifier les changements manqués

Des webhooks peuvent être manqués (indisponibilité plus longue que la fenêtre de réessai, endpoints désactivés). Appelez régulièrement GET /v1/notes?updated_after=<last sync> pour vous remettre à jour.
Un note.deleted accompagné de reason: "access_lost" signifie que la note est sortie du périmètre de vos identifiants (par exemple une note personnelle déplacée dans un espace d'équipe). Traitez-le exactement comme une suppression : supprimez votre copie ou bloquez-y l'accès.
Le polling incrémental seul ne permet de détecter ni les suppressions ni les pertes d'accès. Listez périodiquement toutes les notes (avec include_deleted=true pour voir les tombstones) : tout identifiant de note que vous conservez et qui n'apparaît plus a été supprimé ou est sorti de votre périmètre.