Webhooks

Webhooks entregam eventos por HTTP. O receptor deve validar a autenticidade antes de interpretar o payload e responder rapidamente para evitar tentativas desnecessárias.

Endpoint receptor

POSThttps://cliente.com/webhooks/ibpms

Exemplo conceitual de endpoint mantido pelo cliente.

Headers de assinatura

Os nomes abaixo representam a convenção preparada para a documentação de webhooks iBPMS. Confirme o contrato do evento publicado antes de integrar um ambiente real.

Campo	Tipo	Obrigatório	Descrição
x-ibpms-signatureAssinatura	STRING	Sim	Assinatura do conteúdo entregue.
x-ibpms-timestampTimestamp	STRING	Sim	Instante usado na validação contra replay.
x-ibpms-event-idEvent ID	STRING	Sim	Identificador para deduplicação.

Payload conceitual

{
  "event": "process.completed",
  "data": {}
}

Contrato conceitual

Os headers e o payload desta página são o formato-alvo para integrações assinadas. Eles não substituem o contrato versionado de um webhook específico.

Validação segura

1. Leia o corpo bruto sem normalizar o JSON.
2. Valide se o timestamp está dentro da janela aceita.
3. Calcule a assinatura com o segredo associado ao endpoint.
4. Compare assinaturas em tempo constante.
5. Rejeite um event-id já processado.
6. Registre o resultado sem persistir segredo ou payload sensível.

Idempotência e retry

Responda com sucesso somente após garantir que o evento foi aceito de forma durável. Se o processamento for demorado, persista-o em uma fila e responda; use o identificador do evento para impedir efeitos duplicados.

Troubleshooting

• 401: assinatura ou segredo incompatível;
• 408/timeout: o receptor não respondeu dentro do limite;
• evento repetido: tentativa legítima ou resposta perdida; deduplique pelo ID;
• timestamp expirado: relógio desalinhado ou entrega fora da janela de segurança.