Como configuro webhooks no painel?

Um webhook avisa o seu sistema quando algo acontece na conta — uma cobrança aprovada, uma assinatura cancelada — com um POST assinado. São mais de 50 tipos de evento, listados no catálogo de eventos da documentação. Tudo fica na Workbench, no menu lateral do painel (também dá para abrir por Configurações → Desenvolvedores).

Criar o endpoint

1. Abra a Workbench e vá na aba Webhooks.
2. Clique em Criar endpoint.
3. Preencha o Nome e a URL, que precisa ser https — por exemplo, https://suamarca.com.br/webhooks/selectwin.
4. Em Eventos, use Escolher para marcar os que interessam, ou Todos, inclusive os que vierem depois.
5. Se o seu servidor exigir, preencha o Cabeçalho Authorization (opcional).
6. Clique em Criar endpoint e guarde o segredo de assinatura (whsec_...): ele aparece uma vez só.
7. Clique em Enviar teste. Chega um evento webhook.ping e você vê o que o seu servidor respondeu.

1234

1. 1O Nome e a URL, que precisa ser https.
2. 2Em Eventos, Escolher ou Todos, inclusive os que vierem depois.
3. 3Cabeçalho Authorization (opcional), se o seu servidor exigir.
4. 4Clique em Criar endpoint e guarde o segredo whsec_....

O endpoint vale para o ambiente em que o painel está: crie um em Sandbox para testar e outro em Produção.

Conferir a assinatura

Cada entrega traz o cabeçalho X-Selectwin-Signature com um HMAC-SHA256 do corpo bruto, calculado com o seu segredo, no formato sha256=<hex>. Recalcule no seu servidor e recuse o que não bater: o passo a passo, com exemplos de código, está em como verificar a assinatura. Responda com um código 2xx logo, em até 30 segundos, e processe depois; sem resposta 2xx, tentamos de novo por cerca de 3 dias. O mesmo evento pode chegar mais de uma vez, então use o id do evento para não processar em dobro.

Reenviar e trocar o segredo

• Em Eventos, Reenviar para todos manda um evento de novo. Em Falhas, Reenviar agora repete uma entrega; na entrega que esgotou as tentativas, o botão é Reenviar o evento.
• No menu do endpoint, Rotacionar o segredo gera um novo. O antigo continua assinando junto por 24 horas, nos cabeçalhos terminados em -Previous, para você trocar sem perder evento.
• Se o endpoint falhar sem parar por um tempo, a proteção automática o desliga. Corrija o servidor e ligue de novo em Ativo.

Se as entregas continuarem falhando, fale com o suporte.