Webhooks
Receba no seu servidor avisos de novos assinantes, descadastros e do resultado das campanhas, com assinatura HMAC.
Loading documentation…
Powered by heyo
O Pushwi pode avisar o seu sistema quando algo acontece no site, com um POST para uma URL que você define. Cada site tem um endereço de webhook e escolhe quais eventos quer receber.
Em Desenvolvedor › Webhooks no painel:
http ou https;Sem URL ou sem segredo, nada é enviado. Endereços que apontam para a rede interna (localhost, IPs privados) são recusados. Para testar localmente, use um túnel como o cloudflared ou o ngrok.
| Evento | Quando |
|---|---|
subscriber.created | Um dispositivo novo se inscreveu |
subscriber.unsubscribed | Um dispositivo ou um assinante foi descadastrado |
campaign.sent | Uma campanha terminou de sair |
campaign.failed | Uma campanha não pôde ser enviada |
Cliques e entregas individuais não geram webhook. Esses números ficam nos relatórios do painel.
Todo webhook é um POST com Content-Type: application/json e este envelope:
Disparado só quando o endpoint é novo para o site. A reinscrição de um navegador já conhecido não gera evento. external_id vem null para assinantes anônimos. Um assinante que já existia pode aparecer de novo quando inscreve outro aparelho, então trate subscriber_id como chave e não duplique registros.
Disparado em dois casos:
| Origem | subscription_id |
|---|---|
O navegador cancelou a inscrição pelo SDK (pushwi("unsubscribe")) | O dispositivo que saiu |
| Alguém descadastrou o assinante inteiro pelo painel | null, porque todos os dispositivos dele saíram de uma vez |
O evento sai uma vez por descadastro: cancelar de novo um dispositivo que já estava descadastrado não gera outro. O assinante pode continuar com outros aparelhos ativos, então não trate o evento como "a pessoa saiu de tudo" quando subscription_id vier preenchido.
Dispositivos que expiram (o serviço de push recusou a inscrição) e assinantes apagados por Excluir assinante não geram este evento.
| Campo | Quando aparece |
|---|---|
recipient_count | Quantos dispositivos estavam no público do envio. 0 quando o público estava vazio. |
send_limit_reached | true quando o limite de envios do plano cortou a campanha no meio |
winner_variant_id | Em teste A/B de duas fases, no aviso enviado depois do vencedor. Esse aviso não traz recipient_count. |
incomplete | true quando o envio travou e o Pushwi encerrou a campanha com o que já tinha saído |
Campanhas recorrentes geram um campaign.sent a cada envio, cada um com o campaign_id da cópia.
reason | Significado |
|---|---|
plan_limit_exceeded | O limite de envios do mês acabou |
service_interrupted | A organização está suspensa |
dispatch_failed | Erro ao montar o envio |
nothing_was_delivered | Nenhum dispositivo aceitou a notificação |
ab_test_phase_one_delivered_nothing | A primeira fase do teste A/B não entregou nada, então não houve vencedor |
stuck_while_queuing, stuck_while_sending | O envio parou de avançar e foi encerrado |
Cada chamada traz o cabeçalho Signature: o HMAC-SHA256, em hexadecimal, do corpo da requisição exatamente como chegou, usando o segredo do webhook como chave. Calcule sobre o corpo bruto, antes de qualquer parse de JSON. Reserializar o JSON pode mudar espaços ou escapes e quebrar a comparação.
O envelope não tem timestamp assinado. Se quiser recusar reenvios antigos, compare sent_at com a hora atual depois de validar a assinatura.
O Pushwi espera até 3 segundos por uma resposta 2xx. Redirecionamentos não são seguidos e contam como falha. Se a chamada falhar, são três tentativas no total: a segunda 10 segundos depois e a terceira 100 segundos depois. Esgotadas as três, o evento é descartado.
Por isso: