Webhooks do Realtime
A publicação envia eventos para os clientes. Webhooks funcionam na direção oposta: o edge do Realtime faz POST de um evento assinado para o seu endpoint quando algo acontece em um canal.
Você já pode consultar o estado de um canal sob demanda com Consultando o estado do canal. Webhooks são a forma de saber sobre uma mudança no momento em que ela acontece, sem polling: um cliente se inscrevendo, um membro fechando sua última aba, um cliente enviando a posição do cursor para outro.
Os cinco grupos de eventos
Inscreva-se em um ou mais grupos de eventos:
| Grupo | A pergunta que ele responde | O que ele entrega |
|---|---|---|
| realtime.channel_existence | Alguém está ouvindo? | realtime.channel_occupied, realtime.channel_vacated |
| realtime.presence | Quem está aqui? | realtime.member_added, realtime.member_removed |
| realtime.connection_count | Quantas conexões? | realtime.connection_count |
| realtime.cache_channels | Este canal precisa de dados? | realtime.cache_miss |
| realtime.client_events | O que os clientes estão enviando? | um evento por evento de cliente, com o mesmo nome |
channel_existence reporta apenas as duas extremidades da vida de um canal: channel_occupied quando ele passa de zero conexões para uma, channel_vacated quando a última conexão sai. Assinantes chegando e saindo entre esses momentos não produzem nada, o que o torna a forma barata de saber se vale a pena publicar.
connection_count exige contagem de conexões no app. Se a configuração estiver desativada, o grupo inscrito não produz eventos.
Inscrever um endpoint
Acesse Webhooks, crie ou edite um endpoint e encontre a seção Realtime events. Selecione um app Realtime e os grupos que deseja receber.
Inscrições de eventos de plataforma se aplicam a todo o espaço de trabalho, enquanto inscrições realtime.* pertencem a um único app. Você não pode alterar o app Realtime do endpoint após criá-lo, mas pode atualizar os grupos inscritos.
Eventos de plataforma e do Realtime podem compartilhar um endpoint. Por exemplo, um endpoint pode se inscrever em email.bounced e realtime.presence. Ambos usam o signing secret do endpoint.
Os grupos do Realtime são configuráveis apenas pelo dashboard. Uma solicitação pública POST /v1/webhooks que inclua um tipo de evento realtime.* é rejeitada, então configure essas inscrições no dashboard.
Como é uma entrega
Cada POST contém um evento no envelope de webhook padrão do Bird:
Exemplo de código
{
"data": { "channel": "presence-room-1", "member_id": "u_42" },
"timestamp": "2026-07-31T09:00:00Z",
"type": "realtime.member_added"
}type identifica o evento entregue. Por exemplo, o grupo realtime.presence entrega realtime.member_added e realtime.member_removed:
| type entregue | Campos de 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, mais member_id em um canal de presença |
Para eventos de cliente, o cliente escolhe o sufixo do evento. Disparar client-typing produz realtime.client-typing, e data.event contém client-typing. Veja Eventos de cliente.
Verificando uma entrega
Os webhooks do Realtime seguem o Standard Webhooks e incluem os headers webhook-id, webhook-timestamp e webhook-signature. Verifique-os com o signing secret do endpoint.
Exemplo de código
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;
}
});Verifique o corpo bruto da requisição porque fazer parse e re-serializar JSON pode alterar os bytes assinados. Trate tipos de evento desconhecidos em um branch default para que novos tipos não quebrem o endpoint. Veja Verificar assinaturas de webhook para o contrato completo.
Eventos de presença contam membros
member_added e member_removed seguem a identidade, então não correspondem um-para-um com conexões. Alguém com seu app aberto em três abas é um único membro:
| O que acontece | Webhook |
|---|---|
| Primeira aba se inscreve | realtime.member_added |
| Segunda aba se inscreve | nenhum |
| Segunda aba fecha | nenhum |
| Última aba fecha | realtime.member_removed |
Use member_removed para detectar quando uma identidade sai de um canal. O encerramento de uma única sessão não o dispara enquanto outra sessão permanece. Para rastrear conexões, inscreva-se em realtime.connection_count. Veja Canais de presença.
Comportamento de entrega dos webhooks do Realtime
As entregas do Realtime seguem estas regras de retentativa e visibilidade:
- Retorne 2xx prontamente após aceitar o evento de forma durável e depois processe-o de forma assíncrona.
- Se o seu endpoint retornar uma resposta diferente de 2xx, o Realtime tenta novamente com backoff exponencial por até 5 minutos.
- Eventos do Realtime não têm replay e não aparecem no log de tentativas de entrega do endpoint.
- Pausar o endpoint interrompe as entregas do Realtime junto com todo o resto, e reativá-lo as retoma.
As entregas não têm ordem e não fornecem confirmação por evento. Trate-as como notificações de mudança. Use Consultando o estado do canal para obter o estado atual após eventos atrasados ou ausentes.
Próximos passos
- Eventos de cliente é o grupo cujos nomes de evento e payloads você mesmo define.
- Canais de cache explica o que fazer com realtime.cache_miss.
- Webhooks e eventos cobre configuração de endpoint, verificação de assinatura e rotação de secret para todo webhook do Bird.
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Explore a funcionalidadeRealtimeSiga o percurso de aprendizagemBuild your first integrationGuia de implementaçãoSend your first realtime event
Experimente na prática e obtenha um resumo de implementação