Webhooks
Catálogo de eventos
O nome de cada evento é estável: ele não muda quando o sistema por dentro muda. Evento novo entra neste catálogo e chega aos endpoints que escolheram "todos".
O conteúdo das mensagens não vai no webhook: o evento diz o que aconteceu e em qual conversa, e o texto fica na Torqyn, porque é dado pessoal.
ping
Evento de teste
O botão "Enviar evento de teste" e POST /v1/webhook-endpoints/{id}/test. Todo endpoint recebe, escolhido ou não.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "ping",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "ping",
"message": "Evento de teste: se chegou, o endereço e a assinatura estão certos."
}
}
}contact.opted_out
Contato pediu para sair
A pessoa pediu para não receber mais mensagens (em qualquer canal). Pare de mandar mensagens de marketing para ela no seu sistema também.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "contact.opted_out",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "contact",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
},
"channel": null
}
}
}message.received
Mensagem recebida
O contato mandou uma mensagem. O corpo traz a conversa e o canal, não o texto: o conteúdo é dado pessoal e fica na Torqyn.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "message.received",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "message",
"id": "7e1f3a5b-2c4d-4e6f-8a9b-0c1d2e3f4a5b",
"direction": "inbound",
"status": "received",
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"channel": "whatsapp",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}message.sent
Mensagem enviada
Uma mensagem nossa (da IA ou do time) saiu para o canal.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "message.sent",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "message",
"id": "3a5c7e9b-1d2f-4a6b-8c0d-2e4f6a8b0c1d",
"direction": "outbound",
"status": "sent",
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"channel": "whatsapp",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}message.delivered
Mensagem entregue
O canal confirmou que a mensagem chegou ao aparelho da pessoa.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "message.delivered",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "message",
"id": "3a5c7e9b-1d2f-4a6b-8c0d-2e4f6a8b0c1d",
"direction": "outbound",
"status": "delivered",
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"channel": "whatsapp",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}message.read
Mensagem lida
A pessoa abriu a mensagem (quando o canal informa leitura).
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "message.read",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "message",
"id": "3a5c7e9b-1d2f-4a6b-8c0d-2e4f6a8b0c1d",
"direction": "outbound",
"status": "read",
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"channel": "whatsapp",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}message.failed
Mensagem não entregue
O canal recusou a mensagem. O motivo aparece no painel, na conversa.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "message.failed",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "message",
"id": "3a5c7e9b-1d2f-4a6b-8c0d-2e4f6a8b0c1d",
"direction": "outbound",
"status": "failed",
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"channel": "whatsapp",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}conversation.handed_off
Conversa passou para o time
A IA chamou alguém do time, ou alguém do time assumiu a conversa.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "conversation.handed_off",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "conversation",
"id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"channel": "whatsapp",
"handed_off_by": "ai",
"case_id": "2c4e6a8b-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}appointment.created
Horário marcado
Um horário foi marcado, pela conversa, pela página ou pelo time.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "appointment.created",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "appointment",
"case_id": "2c4e6a8b-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
"flow": "scheduling",
"starts_at": "2026-10-03T18:00:00.000Z",
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}payment.succeeded
Pagamento confirmado
O provedor de pagamento confirmou um pagamento na conta de recebimento do negócio.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "payment.succeeded",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "payment",
"amount_cents": 15000,
"currency": "BRL",
"case_id": "2c4e6a8b-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}case.stage_changed
Caso mudou de etapa
O caso mudou de coluna no quadro, com a etapa de antes e a de agora.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "case.stage_changed",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "case",
"id": "2c4e6a8b-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
"flow": "sales",
"stage": "proposal_sent",
"previous_stage": "engaged",
"value_cents": 15000,
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}case.won
Caso ganho
O caso fechou com resultado bom (venda, comparecimento, atendimento resolvido), confirmado na origem ou marcado pelo time.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "case.won",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "case",
"id": "2c4e6a8b-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
"flow": "sales",
"stage": "won",
"result": "won",
"outcome": "sale_won",
"value_cents": 15000,
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}case.lost
Caso perdido
O caso fechou sem o resultado (perdido, faltou, cancelado).
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "case.lost",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "case",
"id": "2c4e6a8b-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
"flow": "sales",
"stage": "lost",
"result": "lost",
"outcome": "sale_lost",
"value_cents": 15000,
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}event.delivered
Evento entregue
Um evento que o seu sistema mandou (POST /v1/events) virou mensagem.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "event.delivered",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "event",
"type": "consulta_amanha",
"status": "delivered",
"reason": null,
"via": "template",
"channel": "whatsapp",
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}event.failed
Evento não entregue
Um evento que o seu sistema mandou não virou mensagem, e o motivo vem no corpo.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "event.failed",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "event",
"type": "consulta_amanha",
"status": "failed",
"reason": "outside_window",
"via": null,
"channel": null,
"conversation_id": null,
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}