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"
}
}
}
}
contact.trust_changed
Nível de confiança mudou
O time conferiu a identidade do contato (ou retirou uma prova) e o nível de confiança mudou. O corpo traz só o nível novo e o anterior, nunca o documento.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "contact.trust_changed",
"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"
},
"trust_level": "platina",
"previous_level": "ouro"
}
}
}
contact.client_status_changed
Contato virou cliente ou deixou de ser
O contato mudou de estado: virou cliente (resultado bom, carteira, base do negócio ou o time) ou deixou de ser (ex-cliente). O corpo traz o estado novo, o anterior e a origem.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "contact.client_status_changed",
"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"
},
"client_status": "client",
"previous_status": "lead",
"origin": "outcome"
}
}
}
envelope.sent
Documento mandado para assinar
Um contrato, termo ou orçamento foi mandado ao contato para assinar.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "envelope.sent",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "envelope",
"id": "3c5e7a9b-1d2f-4a6b-8c0d-2e4f6a8b0c1d",
"code": "DOC-3C5E7A9B1D",
"kind": "contract",
"status": "sent",
"signer_role": null,
"method": null,
"final_sha256": null,
"value_cents": 150000,
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}
envelope.signed
Alguém assinou
Uma das pessoas assinou o documento (o contato ou a empresa). O corpo diz quem, pelo papel, e como.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "envelope.signed",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "envelope",
"id": "3c5e7a9b-1d2f-4a6b-8c0d-2e4f6a8b0c1d",
"code": "DOC-3C5E7A9B1D",
"kind": "contract",
"status": "sent",
"signer_role": "customer",
"method": "link e código por e-mail",
"final_sha256": null,
"value_cents": 150000,
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}
envelope.declined
Documento recusado
Quem devia assinar recusou, e o documento fechou.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "envelope.declined",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "envelope",
"id": "3c5e7a9b-1d2f-4a6b-8c0d-2e4f6a8b0c1d",
"code": "DOC-3C5E7A9B1D",
"kind": "contract",
"status": "declined",
"signer_role": "customer",
"method": "link e código por e-mail",
"final_sha256": null,
"value_cents": 150000,
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}
envelope.completed
Documento concluído
Todos assinaram. O corpo traz o código e o SHA-256 do arquivo final; o documento se confere em /verificar/<código>.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "envelope.completed",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "envelope",
"id": "3c5e7a9b-1d2f-4a6b-8c0d-2e4f6a8b0c1d",
"code": "DOC-3C5E7A9B1D",
"kind": "contract",
"status": "completed",
"signer_role": null,
"method": null,
"final_sha256": "9f2c5e8a1b4d7f0a3c6e9b2d5f8a1c4e7b0d3f6a9c2e5b8d1f4a7c0e3b6d9f2a",
"value_cents": 150000,
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}
referral.converted
Indicação convertida
Alguém que chegou indicado fechou com o negócio (resultado confirmado na origem). O contato é o indicado; quem indicou recebe a recompensa pelo programa.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "referral.converted",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "referral",
"id": "4d6f8a0c-2e4a-4b6c-8d0e-1f3a5c7e9b2d",
"case_id": "2c4e6a8b-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
"value_cents": 15000,
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}
reward.granted
Recompensa concedida
Um contato ganhou crédito, brinde ou bonificação (indicação ou cashback de compra). O saldo é o de GET /v1/contacts/{external_id}/rewards.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "reward.granted",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "reward",
"id": "8b0d2f4a-6c8e-4a1b-9c3d-5e7f9a1b3c5d",
"entry": "grant",
"kind": "credit",
"amount_cents": 2000,
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}
reward.redeemed
Crédito usado
Parte do crédito de um contato foi usada numa compra (pela API ou pelo time).
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "reward.redeemed",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "reward",
"id": "8b0d2f4a-6c8e-4a1b-9c3d-5e7f9a1b3c5d",
"entry": "redeem",
"kind": "credit",
"amount_cents": 1500,
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}
reward.expired
Crédito vencido
O que sobrou de uma concessão de crédito venceu e saiu do saldo.
{
"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"type": "reward.expired",
"api_version": "2026-10-01",
"created": "2026-10-01T12:00:00.000Z",
"livemode": true,
"account": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
"data": {
"object": {
"object": "reward",
"id": "8b0d2f4a-6c8e-4a1b-9c3d-5e7f9a1b3c5d",
"entry": "expire",
"kind": "credit",
"amount_cents": 500,
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}