Référence — webhooks

Un webhook est une adresse de votre système que MeetingHub appelle quand un événement se produit dans un établissement. Il se pose de deux façons :

• par l'établissement, avec la session d'un administrateur, sous /api/institutions/:institutionId/webhooks — la capacité institution.manage, voir Conventions. Une clé d'établissement n'y a pas accès. Ces routes sont décrites ici ;
• par un éditeur partenaire, avec sa clé mhp_…, sous /api/partner/webhooks : posé une fois, le webhook vaut pour tous ses établissements. Voir Éditeurs partenaires.

Dans les deux cas, l'appel envoyé à votre serveur, sa signature et ses réessais sont les mêmes : ils sont décrits à la fin de cette page.

L'objet Webhook

{
  "id": "5a74f72e-81af-402c-a2af-a5ebd35b7bba",
  "url": "https://ent.mon-lycee.fr/hooks/meetinghub",
  "events": ["attendance.closed"],
  "label": "ENT — émargement",
  "enabled": true,
  "disabledReason": null,
  "consecutiveFailures": 0,
  "lastSuccessAt": "2026-10-14T10:30:05.000Z",
  "lastFailureAt": null,
  "createdAt": "2026-09-02T08:00:00.000Z",
  "partnerWebhookId": null

}

Le secret de signature n'est jamais rendu, sauf une fois, à la création.

L'objet Livraison

Une livraison est l'envoi d'un événement à un webhook, avec ses tentatives.

Événements

GET /api/institutions/:institutionId/webhooks

Liste tous les webhooks de l'établissement, coupés compris, et les copies des webhooks de son éditeur partenaire.

Réponse 200 :

{
  "webhooks": [ { "id": "5a74f72e-…", "url": "https://ent.mon-lycee.fr/hooks/meetinghub", "…": "…" } ],
  "events": ["attendance.closed", "session.cancelled", "roster.imported"]

}

POST /api/institutions/:institutionId/webhooks

Crée un webhook et rend son secret, une seule fois.

{
  "url": "https://ent.mon-lycee.fr/hooks/meetinghub",
  "events": ["attendance.closed"],
  "label": "ENT — émargement"

}

Réponse 201 :

{
  "webhook": {
    "id": "5a74f72e-81af-402c-a2af-a5ebd35b7bba",
    "url": "https://ent.mon-lycee.fr/hooks/meetinghub",
    "events": ["attendance.closed"],
    "label": "ENT — émargement",
    "enabled": true,
    "disabledReason": null,
    "consecutiveFailures": 0,
    "lastSuccessAt": null,
    "lastFailureAt": null,
    "createdAt": "2026-09-02T08:00:00.000Z",
    "partnerWebhookId": null,
    "secret": "whsec_Lc68se…"
  },
  "notice": "Ce secret ne sera plus affiché. Copiez-le maintenant."

}

Ces refus portent le code invalid.

Adresses acceptées

La vérification est refaite à CHAQUE appel, sur les adresses obtenues en résolvant le nom : toutes doivent être publiques, et la connexion est faite à l'une d'elles, et à elle seule. Un nom qui résout vers une adresse interne au moment de l'appel est refusé, même s'il était public à la création du webhook.

PATCH /api/institutions/:institutionId/webhooks/:webhookId

Modifie un webhook. Seuls les champs présents sont modifiés.

Une nouvelle url s'applique aussi aux livraisons encore en attente. Un webhook coupé garde ses livraisons en attente ; il les reprend quand on le réactive.

Réponse 200 :

{ "webhook": { "id": "5a74f72e-…", "enabled": true, "…": "…" } 
}

DELETE /api/institutions/:institutionId/webhooks/:webhookId

Supprime un webhook et tout son historique de livraisons.

Réponse 204, sans corps.

GET /api/institutions/:institutionId/webhooks/:webhookId/deliveries

Les livraisons d'un webhook, de la plus récente à la plus ancienne. C'est aussi ainsi que l'établissement suit les livraisons d'un webhook de son éditeur partenaire : par sa copie.

Réponse 200 :

{
  "deliveries": [
    {
      "id": "c1d2e3f4-…",
      "webhookId": "5a74f72e-…",
      "event": "attendance.closed",
      "payload": "{\"event\":\"attendance.closed\",\"id\":\"evt_…\",…}",
      "status": "delivered",
      "attempts": 1,
      "nextAttemptAt": "2026-10-14T10:30:05.000Z",
      "lastAttemptAt": "2026-10-14T10:30:05.000Z",
      "responseStatus": 200,
      "error": null,
      "createdAt": "2026-10-14T10:30:04.000Z"
    }
  ]

}

L'appel envoyé à votre serveur

MeetingHub fait un POST sur l'adresse du webhook.

Le corps :

{
  "event": "attendance.closed",
  "id": "evt_9xK2pQ7rLm3sT8vW",
  "occurredAt": "2026-10-14T10:30:04.118Z",
  "organisationId": "6c1d3a52-7a0e-4f0b-9c55-0a54c3e1f2b8",
  "data": { "sessionId": "9214f192-…", "…": "…" }

}

attendance.closed

Le corps ne contient pas la feuille elle-même : récupérez-la avec une clé de portée attendance:read. Un cours qui n'a rien à relever n'a pas de feuille, et n'émet pas cet événement.

session.cancelled

roster.imported

Il ne contient ni courriel, ni téléphone, ni lien d'activation.

Signature

v1 est un HMAC-SHA256, en hexadécimal minuscule, calculé avec le secret du webhook sur la chaîne suivante :

<t>.<corps brut>

où t est la valeur de t= dans l'en-tête, et le corps brut est la suite exacte d'octets reçue, avant toute analyse du JSON. Le secret s'utilise tel qu'il a été rendu à la création, préfixe whsec_ compris.

La signature est recalculée à chaque tentative : t est l'heure de la tentative, pas celle de l'événement. Refusez un appel dont t s'écarte de plus de 300 secondes de votre horloge : c'est ce qui empêche de rejouer un appel intercepté. Comparez les signatures à temps constant.

Livraison et réessais

Deux conséquences à prévoir de votre côté :

• Au moins une fois. Si votre réponse se perd, la même livraison est renvoyée. Dédoublonnez sur x-meetinghub-delivery.
• Sans ordre garanti. Les livraisons partent en parallèle : ne supposez pas qu'elles arrivent dans l'ordre des événements.

Une livraison abandonnée reste consultable avec GET /api/institutions/:institutionId/webhooks/:webhookId/deliveries ; elle n'est pas renvoyée d'elle-même.