Configurar webhooks de cliente
Registe um recetor HTTPS para os eventos suportados, proteja o segredo de assinatura e use o histórico de entregas para diagnosticar falhas.
- Preparar o recetorUse um endpoint HTTPS público preparado para receber JSON.
- Subscrever eventosIntroduza um nome para o endpoint, o URL e os tipos de evento.
- Proteger a assinaturaGuarde o segredo apresentado uma única vez e valide os pedidos recebidos.
- Consultar entregasUse o estado e os dados da resposta para resolver problemas.
- Manter o endpointRode os segredos ou revogue destinos que já não sejam necessários.
Eventos de cliente suportados
O formulário de cliente disponibiliza os eventos trabalho concluído, fatura emitida e limiar de quota. Selecione apenas os eventos tratados pelo seu recetor. Os endpoints pertencem à sua área pessoal ou à organização selecionada. Os proprietários e administradores da organização podem geri-los; os membros podem consultá-los, mas não alterá-los. Um webhook envia notificações e não altera, por si só, uma encomenda ou fatura.
- Abra Webhooks no contexto da organização pretendida.
- Selecione pelo menos um evento suportado pelo recetor.
- Use endpoints separados para ambientes diferentes.
Registar um destino público
Crie um endpoint com um nome de 2 a 120 caracteres, um URL válido e um ou mais eventos listados. É obrigatório usar HTTPS e um nome de domínio público. Os destinos locais, internos e em IP privado são rejeitados, pelo que um URL de desenvolvimento local não funciona. Submeta apenas quando o recetor puder aceitar JSON e devolver uma resposta HTTP de sucesso.
- Implemente o recetor num endereço HTTPS público e estável.
- Introduza o URL, um nome claro e a seleção de eventos.
- Submeta uma vez e corrija os erros de validação apresentados.
Verificar mensagens assinadas
A criação revela o segredo de assinatura uma única vez. Os pedidos incluem cabeçalhos de evento, entrega, carimbo temporal e assinatura HMAC, além de JSON com o ID do evento, o tipo, a data de criação e os dados. Valide a assinatura com o carimbo temporal e o corpo bruto exato, aplique uma janela temporal razoável e trate IDs repetidos de forma idempotente. Não inclua o segredo nos registos nem nas mensagens de suporte.
- Guarde o segredo na configuração protegida do recetor.
- Valide a assinatura face ao corpo original, sem o alterar.
- Registe os IDs dos eventos para impedir ações de negócio duplicadas.
Consultar o histórico de entregas
A página mostra as 50 entregas mais recentes dos seus endpoints. As respostas HTTP de sucesso ficam marcadas como concluídas. Erros de servidor e limites de pedidos podem ser tentados novamente; outras respostas sem sucesso podem falhar de imediato e as tentativas param ao atingir o limite. O histórico inclui o estado HTTP e uma parte limitada do corpo da resposta ou do erro. Um evento pode não aparecer se não tiver ocorrido ou se o endpoint não estiver subscrito.
- Inspecione o evento, o número de tentativas, o estado e o último erro.
- Corrija a disponibilidade do recetor, a resposta ou a limitação de pedidos.
- Consulte uma entrega posterior e confirme que ficou concluída.
Rodar o segredo de assinatura
A rotação substitui o segredo do endpoint e volta a ativar esse endpoint. Os recetores que só usem o valor antigo rejeitarão os novos pedidos. Prepare a atualização da configuração do recetor, rode a chave na linha do endpoint pretendido, registe o novo valor e implemente-o rapidamente. Se houver comprometimento, rode a chave de imediato e inspecione o histórico de entregas para detetar atividade inesperada.
- Identifique as instâncias do recetor e prepare uma implementação segura.
- Rode o endpoint e guarde o segredo apresentado uma única vez.
- Confirme que uma entrega esperada posterior é concluída.
Substituir ou revogar endpoints
Os controlos de cliente permitem criar, rodar e revogar; não existe uma ação para editar o URL ou a seleção de eventos. Para alterar qualquer um desses dados, crie uma substituição, confirme que recebe os eventos corretos e depois revogue o endpoint anterior. A revogação interrompe futuras entregas e marca o endpoint como inativo. Use-a para destinos antigos ou segredos comprometidos e confirme a lista depois da ação.
- Crie um endpoint de substituição com o URL ou os eventos corrigidos.
- Confirme que a entrega de teste do novo destino é concluída.
- Revogue o endpoint antigo e confirme que ficou inativo.
Perguntas frequentes
Que eventos estão disponíveis?
Trabalho concluído, fatura emitida e limiar de quota.
Posso usar HTTP sem cifragem?
Não. É obrigatório um URL HTTPS público.
Posso voltar a ver o segredo?
Não. Rode o endpoint para obter um novo segredo.
Porque está a entrega pendente?
Um erro temporário do servidor ou um limite pode levar a novas tentativas.
Porque falhou a entrega?
Consulte a resposta e o histórico de tentativas para identificar a causa.
Posso editar o endpoint?
Não. Crie e verifique uma substituição e revogue o endpoint antigo.