Webhooks permitem que sua aplicação seja notificada automaticamente quando ações acontecem na plataforma, sem necessidade de consultas periódicas à API.

O que são Webhooks?

Sempre que um evento ocorre na plataforma, a Digitalizei envia uma requisição HTTP POST para uma URL configurada por você.

Exemplos:

• Novo contato criado
• Contato atualizado
• Nova conversa iniciada
• Mensagem recebida
• Mensagem enviada
• Atendimento transferido
• Atendimento encerrado

Como funciona

Cliente envia mensagem
↓
Evento acontece na plataforma
↓
Digitalizei dispara Webhook
↓
Seu sistema recebe o evento
↓
Automação executa ações

Configuração

A configuração pode ser realizada através da plataforma.

Caminho

Configurações > Integrações > Webhooks

Ao criar uma assinatura:

1. Informe uma URL pública.
2. Selecione os eventos desejados.
3. Salve a configuração.

A Digitalizei passará a enviar requisições HTTP POST para a URL informada.

Requisitos da URL

A URL configurada deve:

• Utilizar HTTPS
• Estar acessível publicamente
• Aceitar requisições HTTP POST
• Retornar status HTTP 200

Exemplo:

https://api.seusistema.com/webhooks/digitalizei

Pausando Webhooks

Caso necessário, uma assinatura pode ser desativada temporariamente.

Nenhum evento será enviado enquanto a assinatura estiver inativa.

Ciclo de Vida da Conversa

A imagem abaixo demonstra a sequência típica de eventos durante um atendimento.

Estrutura do Payload

Todos os webhooks são enviados utilizando:

Content-Type: application/json

Estrutura padrão:

{
  "eventType": "NOME_DO_EVENTO",
  "date": "2025-01-01T12:00:00Z",
  "content": {}
}

Campos

eventType

Nome do evento disparado.

Exemplos:

CONTACT_CREATED
CONTACT_UPDATED
SESSION_CREATED
MESSAGE_RECEIVED
MESSAGE_SENT
SESSION_UPDATED
SESSION_ENDED

date

Data e hora da geração do evento.

Formato:

YYYY-MM-DDTHH:mm:ssZ

content

Objeto contendo os dados específicos do evento.

O conteúdo varia conforme o tipo do webhook.

Exemplo de Evento

Exemplo de atualização de contato:

{
  "eventType": "CONTACT_UPDATED",
  "date": "2023-08-23T16:42:35.4359934Z",
  "content": {
    "id": "ed2b52f8-cf13-449b-b3d5-ae27051f4663",
    "name": "João Raymond Legrasse",
    "phoneNumber": "+551000000000",
    "email": "[email protected]",
    "status": "ACTIVE"
  }
}

Boas práticas

Responda rapidamente

O webhook deve responder rapidamente com:

200 OK

Mesmo que o processamento seja realizado posteriormente.

Evite processamentos pesados

❌ Errado

Recebe webhook
↓
Executa 15 chamadas API
↓
Responde

✅ Correto

Recebe webhook
↓
Salva em fila
↓
Responde 200
↓
Processa depois

Trate eventos duplicados

Webhooks podem ser reenviados em alguns cenários.

Sua aplicação deve ser capaz de identificar e ignorar eventos duplicados.

Exemplo para N8N

Fluxo básico:

Webhook Trigger
↓
Switch (eventType)
↓
Executa ação correspondente

Exemplos:

CONTACT_CREATED
↓
Criar Lead CRM

MESSAGE_RECEIVED
↓
Acionar IA

SESSION_ENDED
↓
Enviar pesquisa NPS

Eventos Disponíveis

Contatos

CONTACT_CREATED
CONTACT_UPDATED

Conversas

SESSION_CREATED
SESSION_UPDATED
SESSION_ENDED

Mensagens

MESSAGE_RECEIVED
MESSAGE_SENT

Perguntas Frequentes

Qual método HTTP é utilizado?

POST

Qual formato é enviado?

application/json

Preciso consultar a API depois?

Não necessariamente.

Na maioria dos casos os dados necessários já são enviados dentro do campo:

content

O que acontece se minha URL estiver fora do ar?

Os eventos poderão deixar de ser entregues.

Recomendamos monitorar continuamente seus endpoints.