POST que a Timely.ai envia automaticamente para a URL que você configurar sempre que um evento relevante acontece no seu workspace. Em vez de ficar fazendo polling na API, você recebe os dados na hora — sem latência, sem desperdício de requisições.
Por que usar webhooks
Com webhooks você consegue:- Sincronizar seu CRM toda vez que um contato novo entrar ou uma conversa mudar de status
- Disparar automações externas (Make, n8n, Zapier, seu próprio backend) em resposta a eventos
- Alimentar dashboards de BI com dados em tempo real
- Integrar sistemas de atendimento próprios recebendo mensagens assim que chegam
- Monitorar saúde dos canais quando uma conexão cai ou apresenta erro
Como funciona
Você registra um endpoint
Cria um webhook no dashboard ou via API informando a URL do seu servidor e quais categorias de eventos quer receber.
Um evento acontece
Um contato envia uma mensagem, uma conversa é fechada, um agendamento é criado — qualquer coisa que você subscreveu.
A Timely.ai faz um POST
Enviamos um
POST com o payload JSON do evento para a sua URL, com o header X-Timely-Signature para você validar a autenticidade.Desenvolvimento vs Produção
- Desenvolvimento
- Produção
Segurança: validação HMAC
Cada entrega inclui o headerX-Timely-Signature com o formato sha256=HEX. Esse valor é o HMAC-SHA256 do body da requisição usando o secret gerado no momento da criação do webhook.
Nunca ignore a validação. Qualquer servidor na internet poderia postar dados falsos na sua URL se você não verificar a assinatura.
Retentativas automáticas
Se a sua URL não responder2xx dentro de 10 segundos, a Timely.ai retenta automaticamente com backoff exponencial:
| Tentativa | Aguarda antes de retentar |
|---|---|
| 1ª falha | 5 segundos |
| 2ª falha | 15 segundos |
| 3ª falha | 60 segundos |
| 4ª falha | 5 minutos |
| 5ª falha | 15 minutos |
failing e você recebe um email de alerta. O webhook continua ativo — novos eventos continuam sendo enfileirados — mas você precisa verificar o endpoint antes que mais entregas falhem.
Consulte o histórico de entregas no endpoint
GET /v1/webhooks/{id}/deliveries para ver o status de cada tentativa, o código HTTP retornado e o tempo de resposta.Como criar um webhook
- Dashboard
- API
- Acesse Configurações → Webhooks no menu lateral
- Clique em Novo webhook
- Informe a URL de destino e selecione os eventos que quer receber
- Copie o secret gerado — ele aparece apenas uma vez
- Salve e use o botão Testar para validar a entrega
Boas práticas
Responda rapido
Retorne
200 OK imediatamente e processe o evento de forma assíncrona (fila, worker, task). Nunca faça chamadas de banco ou APIs de terceiros antes de responder.Idempotência por event_id
Todo payload inclui um campo
event_id único. Armazene os IDs processados e ignore duplicatas — retentativas podem re-entregar o mesmo evento.Secret em cofre
Nunca exponha o secret em variáveis de ambiente não criptografadas em CI, logs ou código-fonte. Use um secret manager dedicado.
Monitore falhas
Configure alertas no seu lado também. Use
GET /v1/webhooks/{id}/deliveries periodicamente ou integre com seu sistema de observabilidade.Categorias de eventos
Veja a documentação detalhada de cada categoria de evento:Conversas
conversation.created, .assigned, .closed, .reopenedMensagens
message.received, .sent, .failed, .delivered, .readContatos
contact.created, .updated, .deletedAgente
agent.handoff_started, .handoff_completed, .transferredAgendamentos
appointment.scheduled, .rescheduled, .canceled, .reminder_sentCanais
channel.connected, .disconnected, .errorBilling
credit.low, .depleted, plan.changed, trial.expiring, .expired