Documentação

A API de WhatsApp do Talaria

Webhooks

Cada endpoint recebe os eventos que escolher (types, com curingas como message.*) das instâncias que escolher.

curl
curl https://talaria-api.rrlabs.io/v1/webhooks \
  -H "Authorization: Bearer $TALARIA_KEY" \
  -d '{"url": "https://seu.sistema/talaria", "types": ["message.*", "session.state"], "signature": "standard"}'

# 201: o segredo aparece só agora
{ "id": "wh_...", "secret": "whsec_...", ... }

Assinaturas

standard (Standard Webhooks): cabeçalhos webhook-id, webhook-timestamp e webhook-signature: v1,<base64>, o HMAC-SHA256 de id.timestamp.corpo com a chave whsec_… decodificada de base64. hmac_sha512: X-Webhook-Hmac, o HMAC-SHA512 hexadecimal do corpo cru, com o segredo hsec_… inteiro como chave. O webhook_url de uma instância é assinado dos dois jeitos, com o segredo da conta (em Chaves de API).

node
// Standard Webhooks: assinatura = base64(HMAC-SHA256(chave, id + "." + timestamp + "." + corpo))
const key = Buffer.from(secret.replace("whsec_", ""), "base64");
const signed = `${headers["webhook-id"]}.${headers["webhook-timestamp"]}.${rawBody}`;
const expected = "v1," + crypto.createHmac("sha256", key).update(signed).digest("base64");
if (!headers["webhook-signature"].split(" ").includes(expected)) throw new Error("assinatura inválida");

Novas tentativas e reenvio

Em 5 s, 30 s, 2 min, 10 min, 30 min, 1 h, 3 h, 6 h e 12 h, por 24 h; um 410 encerra. As tentativas ficam 7 dias em GET /v1/webhooks/{id}/deliveries e no painel, que reenvia com um clique (POST /v1/webhooks/{id}/replay).