O que são webhooks
Webhooks permitem que a Cordialy notifique seu sistema quando eventos acontecem — sem você precisar fazer polling à API. São ideais para sincronização em tempo real com CRMs, ERPs e automações. Configure em Plataforma → Integrações → Webhooks.Eventos disponíveis
Formato do payload
Todos os eventos seguem a mesma estrutura:Payload por evento
lead.created
lead.created
message.received
message.received
session.ended
session.ended
Validar a assinatura
Cada requisição inclui o headerX-Cordialy-Signature com um HMAC-SHA256 do payload assinado com seu Webhook Secret. Valide sempre antes de processar:
Retry automático
Se seu endpoint retornar status diferente de2xx, a Cordialy tentará reenviar com backoff exponencial:
Após 5 tentativas sem sucesso, o evento é descartado.
Boas práticas
Responda rápido, processe depois
Responda rápido, processe depois
Retorne
200 OK imediatamente e processe o evento em background. Endpoints lentos causam timeouts e retries desnecessários.Torne o handler idempotente
Torne o handler idempotente
Por causa dos retries, o mesmo evento pode chegar mais de uma vez. Use o
message_id ou lead_id + timestamp como chave de deduplicação.Use HTTPS com certificado válido
Use HTTPS com certificado válido
O endpoint precisa ser HTTPS com certificado válido. HTTP ou certificados autoassinados são rejeitados.