Como Receber Webhooks¶

Contexto¶

Um webhook é uma maneira eficiente de receber notificações e dados em tempo real de sistemas externos.

Ao configurar uma URL em seu sistema, você pode permitir que outros serviços publiquem informações para essa URL sempre que um evento relevante acontecer. Isso significa que, em vez de precisar consultar constantemente esses sistemas para obter atualizações, os dados chegam automaticamente, assim que ocorrem.

Essa abordagem é especialmente útil para automatizar processos e reagir instantaneamente a eventos importantes, como novas transações, atualizações de pedidos ou mudanças em dados, economizando tempo e recursos.

Esta documentação visa esclarecer o comportamento dos nossos webhooks, facilitando sua integração e garantindo um processo de implementação mais ágil e eficiente.

Formato Padrão das Mensagens de Webhook¶

As mensagens enviadas pelo webhook têm o propósito exclusivo de notificar sobre a ocorrência de alterações em registros, sem fornecer detalhes completos sobre a mudança em si. Esse modelo simplificado contribui para manter a comunicação via webhook segura e eficiente.

Após o recebimento de uma notificação de webhook, é comum que seu sistema realize uma consulta adicional à API para obter detalhes completos sobre o registro alterado.

Cada mensagem de webhook contém os seguintes elementos:

status: Indica o tipo de alteração realizada no objeto, como CREATION, UPDATE, etc.
params: Um dicionário que contém os parâmetros necessários para identificar o recurso afetado.
resource: A URI do recurso que foi alterado, que pode ser usada para consultar o dado atualizado ou criado.
tenant_id: Identificador do cliente ao qual o evento se refere.
topic: Define a categoria ou tipo de evento, ajudando a classificar a natureza da notificação.

Exemplo de Mensagem¶

{
  "data": {
    "status": "CREATION",
    "params": {
      "id": "debde69a-2dbb-427b-b478-6cffd7930ecf",
    },
    "resource": "/v0/tickets/debde69a-2dbb-427b-b478-6cffd7930ecf"
  },
  "tenant_id": "3b5cf468-c858-404b-9e53-630e3df9d74a",
  "topic": "sac_ticket"
}

Interpretação do Status nas Mensagens de Webhook¶

O campo status indica a operação realizada sobre um registro no sistema e informa ao consumidor do webhook qual ação foi tomada. Os possíveis valores são:

CREATION: Indica uma operação de criação de um registro no tópico especificado.
UPDATE: Indica a atualização de um registro existente.
DELETION: Indica a exclusão de um registro.

⚠️ Se o seu sistema armazena dados das nossas APIs, é fundamental aplicar as atualizações e deleções conforme indicadas, já que podem envolver moderação e remoção de informações sensíveis de clientes.

Tópicos de Inscrição e Exemplos de Notificações¶

Ao se inscrever para receber notificações do nosso webhook, sua URL receberá mensagens referentes a diferentes tópicos, cada um relacionado a um recurso específico. Abaixo está a definição de cada tópico disponível, juntamente com seus possíveis status e um exemplo de mensagem.

Tópico Descrição Possíveis Status Exemplo de Mensagem

sac_ticket

Eventos de tickets de atendimento ao cliente

CREATION, UPDATE, DELETION

{
  "data": {
    "status": "CREATION",
    "params": {
      "id": "debde69a-2dbb-427b-b478-6cffd7930ecf",
    },
    "resource": "/v0/tickets/debde69a-2dbb-427b-b478-6cffd7930ecf"
  },
  "tenant_id": "3b5cf468-c858-404b-9e53-630e3df9d74a",
  "topic": "sac_ticket"
}

sac_message

Eventos de mensagens de ticket de atendimento ao cliente

CREATION, UPDATE, DELETION

{ 
  "data": {
    "status": "CREATION",
    "params": {
      "ticket_id": "debde69a-2dbb-427b-b478-6cffd7930ecf",
      "id": "39697476-cbc3-4154-bf43-165464f66197",
    },
    "resource": "/v0/tickets/debde69a-2dbb-427b-b478-6cffd7930ecf/messages/39697476-cbc3-4154-bf43-165464f66197"
  },
  "tenant_id": "3b5cf468-c858-404b-9e53-630e3df9d74a",
  "topic": "sac_message"
}

Receba Atualizações por Webhook¶

Para configurar um webhook, siga a documentação do portal de desenvolvedores