Skip to main content

​
Conceito

Os Webhooks da Timely.ai são notificações HTTP POST enviadas automaticamente para a URL que você configurar sempre que um evento relevante acontece no workspace — uma mensagem recebida, uma conversa fechada, um contato criado, um canal desconectado, entre outros. Em vez de consultar a API periodicamente para verificar se algo mudou, você recebe o dado assim que o evento ocorre. Cada webhook tem um secret gerado no momento da criação, usado para assinar as entregas com HMAC-SHA256 no header X-Timely-Signature. Isso garante que apenas a Timely.ai pode enviar eventos para o seu endpoint. Para entender como validar a assinatura e implementar um receptor de webhooks, consulte a visão geral de webhooks.

​
Ciclo de vida de um Webhook

criar webhook (URL + eventos + secret gerado)
    │
    ▼
active → Timely entrega eventos para a URL
    │
    ├── evento ocorre → entrega (success ou failure)
    │       │
    │       └── falha → retentativa com backoff exponencial
    │
    ├── testar → entrega de evento sintético
    │
    ├── consultar deliveries → histórico de entregas
    │
    └── deletar → para de receber eventos
Após 5 falhas consecutivas, o webhook é marcado como failing mas continua ativo. Novos eventos continuam sendo enfileirados — você recebe um alerta por email e pode agir antes de perder dados.

​
Campos principais

CampoTipoDescrição
idstring (UUID)ID único do webhook
urlstringURL de destino das entregas (deve ser HTTPS)
eventsarrayLista de categorias de eventos subscritas
statusenumactive | inactive | failing
descriptionstringDescrição interna do propósito do webhook
secretstringSecret HMAC — exibido apenas na criação (write-once)
created_atstringISO 8601 de criação
last_delivery_atstringISO 8601 da última tentativa de entrega
success_ratenumberTaxa de sucesso das últimas 100 entregas (0–1)

​
Campos de uma Delivery

CampoTipoDescrição
idstring (UUID)ID da entrega
webhook_idstring (UUID)Webhook que gerou a entrega
event_typestringTipo do evento entregue
statusenumsuccess | failed | pending
http_statusnumberCódigo HTTP retornado pelo seu servidor
attemptnumberNúmero da tentativa (1 = primeira)
response_time_msnumberTempo de resposta em milissegundos
delivered_atstringISO 8601 da tentativa

​
Categorias de eventos disponíveis

CategoriaEventos
conversation.*created, closed, reopened, assigned
message.*received, sent, delivered, read, failed
contact.*created, updated, deleted
agent.*handoff_started, handoff_completed, transferred
channel.*connected, disconnected, error
credit.*low, depleted
plan.*changed

​
Endpoints disponíveis

Consulte a barra lateral à esquerda para a lista completa de endpoints deste grupo. Cada endpoint tem sua própria página com schema de request/response, exemplos em cURL/JS/Python e playground interativo.

​
Próximos passos

Visão geral de webhooks

Entenda como validar assinaturas e implementar um receptor.

Primeira requisição

Se você ainda não fez sua primeira chamada, comece por aqui.