Webhooks
Cada endpoint recebe os eventos que escolher (types, com curingas como message.*) das instâncias que escolher.
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).
// 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).
Primeiros passos
O Talaria conecta um número como aparelho do WhatsApp Web e dá a você uma API REST, um registro de eventos e webhooks assinados. É uma API de WhatsApp não oficial, não afiliada à Meta.
1. A chave
Crie a conta e escolha um plano. A primeira chave aparece uma única vez no fim do cadastro; outras, em Painel → Chaves de API (guardamos só o hash). Toda chamada leva Authorization: Bearer tk_live_….
2. Uma instância
Cada instância é um número. O plano diz quantas você pode ter; além dele, a API responde 402 plan_limit.
3. Conectar
Pelo QR ({"method": "qr"}: a resposta traz qr e qr_png) ou por código de pareamento, que serve também para fixos. Pedir de novo nunca invalida um QR ou código ainda válido.
4. Enviar
A resposta é 202 com o id da mensagem, que volta em message.sent e message.status. Com Idempotency-Key, repetir a chamada não envia duas vezes.
5. Receber
Pelo registro de eventos (7 dias, com cursor) ou por webhooks. Cada pessoa vem com pn e lid.
Erros
Um status HTTP e {"error": {"code", "message", "details"}}. Os códigos são estáveis: unauthorized, forbidden, not_found, invalid_request, conflict, plan_limit, rate_limited, not_connected, not_on_whatsapp, lid_unresolved, media_unavailable, whatsapp_error, internal.
Webhooks
Cada endpoint recebe os eventos que escolher (types, com curingas como message.*) das instâncias que escolher.
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).
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).
Referência da API
Cada endpoint do contrato (docs/openapi.yaml). Base https://talaria-api.rrlabs.io/v1; JSON em snake_case; listas com ?limit= e ?after=; POSTs aceitam Idempotency-Key. Os marcados em breve estão no contrato e ainda não respondem.