Um webhook envia uma mensagem para um endereço seu sempre que algo acontece no seu espaço de trabalho, por exemplo quando uma encomenda é paga ou uma subscrição é cancelada. Use-o para manter outro sistema sincronizado, como uma ferramenta do tipo Zapier, a sua contabilidade ou o seu próprio servidor.
Abrir as configurações de webhooks
Antes de começar
A página fica em Pagamentos > Configurações > Webhooks, no grupo Desenvolvedores. Vê-la exige Ver pagamentos. Adicionar, alterar, testar e eliminar endpoints exige Atualizar pedidos / clientes.
Adicionar um endpoint
Clique no botão de adicionar para abrir Adicionar endpoint de webhook:
- Em Endpoint, dê-lhe um Nome opcional e introduza o URL do Endpoint. O endereço tem de estar acessível a partir da internet. Os endereços numa rede privada são recusados.
- Em Eventos, escolha o que o endpoint deve receber. Buscar eventos restringe a lista, a caixa de seleção de um grupo seleciona o grupo inteiro, e Selecionar tudo ou Limpar tudo altera tudo de uma vez. É preciso pelo menos um evento.
- Clique em Criar.
Os eventos estão agrupados por tema:
- Pagamentos: Pedido pago, Pagamento em processamento, Pagamento falhou, Fatura paga, Reembolso criado.
- Assinaturas: Assinatura criada, Assinatura renovada, Assinatura cancelada, Pagamento da assinatura falhou.
- Membros: registos, inícios de sessão, etiquetas acrescentadas ou removidas, campos de membro alterados e novos contactos.
- Cursos e eventos, Comunidade e Dados e caixa de entrada: cursos e lições concluídos, inscrições e presenças em eventos, publicações, níveis, medalhas, mensagens da caixa de entrada e tickets.
- Afiliado: novas comissões e pagamentos de comissões efetuados, veja a ajuda de afiliados.
O segredo de assinatura
Logo após criar o endpoint, o espaço de trabalho mostra o seu segredo de assinatura uma única vez: Copie agora o seu segredo de assinatura. Guarde-o do seu lado e clique em Concluído. Não volta a ser mostrado.
Cada entrega é enviada como JSON com o cabeçalho X-Maio-Signature. Este
contém um HMAC-SHA256 do corpo bruto do pedido, feito com o seu segredo, como
uma cadeia hexadecimal em minúsculas. Calcule o mesmo valor do seu lado e
compare-o, para saber que a mensagem veio do seu espaço de trabalho. Os
cabeçalhos X-Maio-Event e X-Maio-Delivery indicam o evento e a entrega.
Para substituir o segredo, abra o endpoint e clique em Rotacionar segredo. O segredo antigo deixa de funcionar de imediato, por isso atualize o seu endpoint logo a seguir.
Testar
Abra o endpoint e clique em Enviar teste. O botão muda para Teste na fila, e um evento de teste chega ao seu endpoint em poucos instantes. Aparece no registo de entregas como qualquer outra entrega.
O registo de entregas
O separador Registro de entrega lista cada entrega com o seu Evento, Endpoint, Status, o estado HTTP com que o seu endpoint respondeu, as Tentativas e Quando. Filtre-o por Entregue, Falhou ou Pendente. A secção Entregas de um endpoint mostra as suas 20 entregas mais recentes, com o erro de cada uma que falhou.
Uma entrega conta como entregue quando o seu endpoint responde com um estado 2xx no prazo de 15 segundos. Caso contrário, é tentada de novo após 30 segundos, 5 minutos, 30 minutos, 2 horas e 6 horas. Reenviar envia de novo uma entrega com o mesmo conteúdo.
Após 20 tentativas falhadas seguidas para um evento, esse evento é desativado para o endpoint. Se o endpoint responder com 410 Gone, o evento é desativado de imediato. Corrija o endpoint e volte a pô-lo em Ativo.
Desativar e eliminar
No endpoint, o interruptor alterna entre Ativo e Desativado. Um endpoint desativado não recebe nada. Excluir remove-o com todos os seus eventos depois de confirmar.
A partir da API
As apps ligadas através da API podem configurar os seus próprios endpoints com
os endpoints /api/v1/hooks e uma chave de API com o âmbito
webhooks:manage. Aparecem na lista com um selo API, e só o nome e o
estado podem ser alterados aqui. Não têm Rotacionar segredo nem Enviar
teste. Veja
Chaves de API e acesso para programadores.