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"
      }
    }
  }
}