group.joined
O número entrou num grupo.
O número da conexão entrou num grupo ou foi adicionado a um. Também é enviado uma vez para cada grupo de que o número já participa quando a conexão dele abre pela primeira vez neste processo do gateway, e não de novo nas reconexões seguintes.
Como toda entrega de webhook é feita pelo menos uma vez, aplique-o de forma idempotente, pela chave data.groupId.
Não é só entrada nova. O anúncio dos grupos existentes volta a acontecer quando a conexão abre num processo novo do gateway (depois de um reinício ou de uma mudança de instância) e depois de um novo pareamento que segue um logout. Por isso, trate group.joined como “o número está neste grupo” e grave o grupo com um *upsert* por groupId, nunca como uma inserção que falha ou duplica.
Campos opcionais. groupName e participantCount ficam fora do objeto quando o gateway não os conhece (por exemplo, quando o WhatsApp não devolve os dados do grupo no momento da entrada). Só groupId vem sempre. Para ter a lista atual, com nome e tamanho, use Listar grupos.
O ciclo de um grupo. Uma mudança de nome chega como group.updated, e a remoção do número como group.left. As mensagens do grupo chegam como message.incoming, com jid igual ao groupId e phone sempre null.
Entrega. Um POST com Content-Type: application/json ao webhookBaseUrl do projeto, feito pelo menos uma vez; um projeto inativo não recebe webhooks. Responda 2xx em até 10 segundos: o corpo da resposta é ignorado, e um redirecionamento (3xx) não é seguido e conta como falha. Uma entrega que falha é tentada de novo depois de cerca de 2, 4, 8, 16 e 32 segundos, 6 tentativas no total, e então fica dead. Depois de 5 falhas seguidas, as entregas do projeto ficam em pausa de 30 segundos a 5 minutos, e um evento que passa 24 horas sem ser entregue também fica dead. Uma nova tentativa pode chegar depois de eventos mais novos: ordene pelo timestamp do envelope. Reenvie as entregas dead com POST /webhooks/deliveries/{id}/resend ou POST /webhooks/deliveries/resend-dead.
Assinatura. X-Webhook-Token vem sempre, com o webhookToken do projeto, junto com os webhookHeaders personalizados. Com um webhookSecret, cada tentativa também traz X-Sales-Timestamp (segundos unix da tentativa) e X-Sales-Signature: calcule "sha256=" + hex(HMAC-SHA256(webhookSecret, X-Sales-Timestamp + "." + corpo)) sobre os bytes do corpo exatamente como chegaram, compare em tempo constante e rejeite um X-Sales-Timestamp a mais de 300 segundos do seu relógio. Veja Webhooks e assinatura.
Guia: Webhooks e assinatura
Cabeçalhos da entrega
X-Webhook-TokenstringsempreO webhookToken do projeto, em toda entrega. Pode ser definido, mas nunca é devolvido pela API: troque-o com PATCH /tenants/{id}. Os webhookHeaders personalizados do projeto também são enviados.
X-Sales-TimestampstringSó quando o projeto tem um webhookSecret: segundos unix desta tentativa de entrega (as novas tentativas são assinadas de novo). Rejeite um que esteja a mais de 300 s do seu relógio.
X-Sales-SignaturestringSó quando o projeto tem um webhookSecret: "sha256=" + hex(HMAC-SHA256(webhookSecret, X-Sales-Timestamp + "." + rawBody)). Calcule sobre os bytes do corpo exatamente como recebidos, nunca sobre um objeto serializado de novo, e compare em tempo constante.
Envelope
typestringsempre presenteO tipo do evento, que decide o formato de data. Ignore os tipos que você não conhece: a lista de eventos pode crescer.
connectionIdstring · uuidsempre presenteO id (UUID) da conexão, ou seja, do número, que gerou o evento.
tenantIdstring · uuidsempre presenteO id (UUID) do projeto dono da conexão.
externalIdstring | nullsempre presenteO externalId que você informou ao criar a conexão, para ligá-la a um registro seu. null quando a conexão foi criada sem ele.
timestampstring · date-timesempre presenteQuando o evento foi gerado, em ISO 8601 (UTC). É o mesmo em todas as tentativas de entrega; o momento de cada tentativa vem no cabeçalho X-Sales-Timestamp.
Campos de data
groupIdstringsempre presenteO JID do grupo (…@g.us). É o mesmo valor que chega em jid nas mensagens do grupo e que serve de to para enviar ao grupo.
groupNamestringO nome (assunto) do grupo. Fica fora do objeto quando não é conhecido.
participantCountnumberQuantos participantes o grupo tem, contando o próprio número. Fica fora do objeto quando não é conhecido.