Webhooks Realtime

La publication envoie des événements aux clients. Les webhooks fonctionnent dans l'autre sens : le edge Realtime envoie par POST un événement signé à votre endpoint lorsque quelque chose se produit sur un channel.

Vous pouvez déjà lire l'état d'un channel à la demande avec Interroger l'état d'un channel. Les webhooks vous informent d'un changement au moment où il se produit, sans polling : un client qui s'abonne, un membre qui ferme son dernier onglet, un client qui envoie une position de curseur à un autre.

Les cinq groupes d'événements

Abonnez-vous à un ou plusieurs groupes d'événements :

Groupe	Question à laquelle il répond	Ce qu'il délivre
realtime.channel_existence	Quelqu'un écoute-t-il ?	realtime.channel_occupied, realtime.channel_vacated
realtime.presence	Qui est présent ?	realtime.member_added, realtime.member_removed
realtime.connection_count	Combien de connexions ?	realtime.connection_count
realtime.cache_channels	Ce channel a-t-il besoin de données ?	realtime.cache_miss
realtime.client_events	Qu'envoient les clients ?	un événement par événement client, portant son nom

channel_existence ne signale que les deux extrémités de la vie d'un channel : channel_occupied lorsqu'il passe de zéro connexion à une, channel_vacated lorsque sa dernière connexion se ferme. Les abonnés qui arrivent et partent entre-temps ne produisent rien, ce qui en fait le moyen économique de savoir si la publication en vaut la peine.

connection_count nécessite le comptage des connexions sur l'app. Si ce paramètre est désactivé, le groupe abonné ne produit aucun événement.

Abonner un endpoint

Ouvrez Webhooks, créez ou modifiez un endpoint, puis trouvez la section Realtime events. Sélectionnez une app Realtime et les groupes à recevoir.

Les abonnements aux événements Platform s'appliquent à l'ensemble de l'espace de travail, tandis que les abonnements realtime.* appartiennent à une seule app. Vous ne pouvez pas changer l'app Realtime de l'endpoint après sa création, mais vous pouvez mettre à jour ses groupes abonnés.

Les événements Platform et Realtime peuvent partager un endpoint. Par exemple, un même endpoint peut s'abonner à email.bounced et realtime.presence. Les deux utilisent le secret de signature de l'endpoint.

Les groupes Realtime ne sont configurables que depuis le tableau de bord. Une requête publique POST /v1/webhooks qui inclut un type d'événement realtime.* est rejetée ; configurez donc ces abonnements dans le tableau de bord.

À quoi ressemble une livraison

Chaque POST contient un événement dans l'enveloppe webhook standard de Bird :

Exemple de code

{
  "data": { "channel": "presence-room-1", "member_id": "u_42" },
  "timestamp": "2026-07-31T09:00:00Z",
  "type": "realtime.member_added"
}

type identifie l'événement livré. Par exemple, le groupe realtime.presence livre realtime.member_added et realtime.member_removed :

type livré	Champs data
realtime.channel_occupied	channel
realtime.channel_vacated	channel
realtime.member_added	channel, member_id
realtime.member_removed	channel, member_id
realtime.connection_count	channel, connection_count
realtime.cache_miss	channel
realtime.<client event>	channel_name, event, data, connection_id, plus member_id sur un channel de présence

Pour les événements client, le client choisit le suffixe de l'événement. Déclencher client-typing produit realtime.client-typing, et data.event contient client-typing. Voir Événements client.

Vérifier une livraison

Les webhooks Realtime suivent le standard Standard Webhooks et incluent les en-têtes webhook-id, webhook-timestamp et webhook-signature. Vérifiez-les avec le secret de signature de l'endpoint.

Exemple de code

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({
  apiKey: process.env.BIRD_API_KEY,
  webhooks: { secret: process.env.BIRD_WEBHOOK_SECRET },
});

app.post("/webhooks/bird", express.raw({ type: "*/*" }), (req, res) => {
  const event = bird.webhooks.unwrap(req.body, req.headers);
  res.sendStatus(200);

  switch (event.type) {
    case "realtime.channel_vacated":
      stopExpensiveWorkFor(event.data.channel);
      break;
    case "realtime.member_removed":
      markAway(event.data.member_id);
      break;
  }
});

Vérifiez le corps brut de la requête, car analyser puis resérialiser JSON peut modifier les octets signés. Gérez les types d'événements inconnus dans une branche default afin que les nouveaux types ne cassent pas l'endpoint. Voir Vérifier les signatures de webhook pour le contrat complet.

Les événements de présence comptent les membres

member_added et member_removed suivent l'identité et ne correspondent donc pas un pour un aux connexions. Une personne ayant votre app ouverte dans trois onglets compte comme un seul membre :

Ce qui se passe	Webhook
Premier onglet s'abonne	realtime.member_added
Deuxième onglet s'abonne	aucun
Deuxième onglet se ferme	aucun
Dernier onglet se ferme	realtime.member_removed

Utilisez member_removed pour détecter le moment où une identité quitte un channel. La fin d'une seule session ne le déclenche pas tant qu'une autre session reste active. Pour suivre les connexions, abonnez-vous à realtime.connection_count. Voir Channels de présence.

Comportement de livraison des webhooks Realtime

Les livraisons Realtime suivent ces règles de réessai et de visibilité :

Renvoyez 2xx rapidement après avoir accepté l'événement de manière durable, puis traitez-le de façon asynchrone.
Si votre endpoint renvoie une réponse non-2xx, Realtime réessaie avec un backoff exponentiel pendant 5 minutes maximum.
Les événements Realtime ne disposent pas de rejeu et n'apparaissent pas dans le journal des tentatives de livraison de l'endpoint.
Mettre l'endpoint en pause arrête les livraisons Realtime ainsi que tout le reste, et le réactiver les reprend.

Les livraisons ne sont pas ordonnées et ne fournissent pas d'accusé de réception par événement. Traitez-les comme des notifications de changement. Utilisez Interroger l'état d'un channel pour récupérer l'état actuel après des événements retardés ou manquants.

Étapes suivantes

Événements client est le groupe dont vous définissez vous-même les noms et les payloads des événements.
Channels de cache explique quoi faire avec realtime.cache_miss.
Webhooks et événements couvre la configuration des endpoints, la vérification des signatures et la rotation des secrets pour chaque webhook Bird.

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Explorer la fonctionnalitéRealtime Suivre le parcours d'apprentissageBuild your first integration Guide d'implémentationSend your first realtime event

Essayez la pratique et obtenez un guide d'implémentation