Um webhook de saída é o mecanismo pelo qual a Dito envia dados da base unificada de consumidores para um sistema externo, por meio de uma requisição HTTP, no momento em que uma funcionalidade da Dito, como Campanha (produto Canais) ou uma Jornada (produto Automações), dispara o uso.

Diferente das integrações de entrada (em que sistemas externos enviam dados para a Dito), o webhook de saída faz a Dito atuar como fonte do dado para o ecossistema do cliente:

📘

A cada disparo, a plataforma monta um payload com os dados do consumidor, aplica uma transformação opcional em JavaScript e executa a requisição configurada contra um endpoint externo.

Esta página descreve o conceito, o contrato da requisição que a Dito envia, a estrutura do payload, a função de transformação e os limites de operação.

Modelo conceitual

Um webhook na Dito é uma definição reutilizável composta por três blocos:

Depois de criado, testado e ativado, o webhook fica disponível para ser selecionado nas funcionalidades do produto, como Canais e Jornadas.

📘

Envio individual

A Dito executa uma requisição por consumidor alcançado pelo disparo.

Fluxo de ponta a ponta

A plataforma externa é responsável por receber a requisição, processá-la (por exemplo, enviar uma mensagem de WhatsApp através de um provedor) e responder com um status HTTP.

A requisição enviada pela Dito

A requisição executada contra o endpoint externo é definida pela configuração do webhook, após a transformação:

• Método: um entre GET, POST, PUT, PATCH, DELETE.
• URL: o endpoint completo configurado (pode ser sobrescrito pela transformação).
• Headers: os pares Nome: Valor configurados (pode ser sobrescrito pela transformação). É aqui que vão as credenciais de autenticação.
• Body: o objeto payload retornado pela transformação, serializado em JSON.

Exemplo de requisição recebida pelo endpoint externo:

POST /webhook HTTP/1.1
Host: api.exemplo.com
Authorization: Bearer token123
Content-Type: application/json

{
  "contact": {
    "name": "João Silva",
    "email": "[email protected]",
    "phone": "+55 11 99999-9999"
  },
  "timestamp": "2026-02-26T13:55:49.027Z"
}

🚧

Autenticação

Nesta fase, a autenticação é feita exclusivamente via headers (ex.: Authorization: Bearer <token>). Esquemas que dependem de algo além do envio de dados no header (OAuth com troca de tokens, assinaturas HMAC negociadas, mTLS, etc.) não fazem parte do escopo atual.

📘

Métodos sem corpo

Para métodos que não trafegam corpo (GET, DELETE), o payload retornado pela transformação não é enviado como body. Use a url e os headers para transportar a informação necessária nesses casos.

Payload de entrada

Antes da transformação, a Dito monta o objeto de entrada a partir de fontes selecionadas na etapa Dados de entrada.

Consumidor

Inclui os dados padrão do consumidor (id, name, email, gender, etc.) e os custom datas cadastrados na Dito.

"user": {  
	"brand": "nome-marca",  
	"id": "11111111111",  
	"email": "[[email protected]](mailto:[email protected])",  
	"name": "João da Silva",  
	"birthday": "2000-01-01",  
	"phone": "319988885188",  
	"custom_data": {  
		"blacklist_email": {  
			"format": "null"  
		},  
		"loja_preferencia": {  
			"value": "0001",  
			"format": "string"  
		}  
	},  
	"address": {  
		"city": "Belo Horizonte",  
		"country": "Brasil",  
		"postal_code": "30140-170",  
		"state": "MG",  
		"street": "Levinto Lopes"  
	},  
	"gender": "male"  
}

Dados relacionados

Além do consumidor, é possível anexar um ou mais conjuntos de dados relacionados:

Campanha

Dados enviados no disparo de uma Campanha no produto Canais:

"campaign": {  
	"brand": "nome-marca",  
	"channel": {  
		"name": "webhook"  
	},  
	"dispatch_id": "897908732abs",  
	"id": "197a3ff3-f31b-4cd0-aa24-c046b85f6e86",  
	"name": "Campanha de pós-venda",  
	"provider": {  
		"name": "webhook"  
	},  
	"tags": [  
		"pos-venda",  
		"marketing"  
	],  
	"type": "CAMPAIGN_TYPE_STANDARD",  
	"utms": {  
		"main": {  
			"campaign": "CAMPANHA_POS_VENDA",  
			"content": "CAMPANHA_POS_VENDA",  
			"medium": "whatsapp",  
			"source": "crm"  
		}  
	}  
}

Evento

O track event usado como gatilho de uma Jornada por comportamento ou de uma Campanha por comportamento:

"event": {  
	"type": "TRACK",  
	"v": "1",  
	"brand": "nome-marca",  
	"message_id": "2d1596b0-d99d-4732-b9f3-19f764c1036c",  
	"action": "comprou",  
	"user_id": "11111111111",  
	"timestamp": "2026-08-05T12:00:00Z",  
	"properties": {  
		"custom_data": {  
			"desconto": {  
				"value": "2",  
				"format": "number"  
			},  
			"id_loja": {  
				"value": "0001",  
				"format": "string"  
			}  
		},  
		"revenue": 100,  
		"currency": "BRL"  
	},  
	"context": {}  
}

📘

Seleção definitiva

A escolha dos dados é fixada na criação e não pode ser alterada na edição. Para mudar o tipo de uso, crie um novo webhook ou duplique o existente.

Parâmetros

Parâmetros são campos definidos no webhook e preenchidos no momento do uso (em Canais ou Jornadas) ou na área de teste. Cada parâmetro tem:

• Nome: identifica o dado.
• Tipo: Texto, Número ou Data (define o campo de input no momento do uso).

Os valores informados ficam disponíveis na transformação em webhook.variables.

Função de transformação

A transformação é uma função JavaScript que recebe os dados de entrada e retorna a estrutura final da requisição. Ela permite formatar, renomear, combinar e validar dados antes do envio.

Contrato

A função recebe um único objeto, webhook, com quatro propriedades:

A função deve sempre retornar um objeto com:

Exemplo básico

function transform(webhook) {  
  const cliente = webhook.payload;

  return {  
    url: webhook.url,  
    headers: webhook.headers,  
    payload: {  
      contact: {  
        name: cliente.name,  
        email: cliente.email,  
        phone: cliente.telefone  
      },  
      timestamp: new Date().toISOString()  
    }  
  };  
}

Exemplo com lógica

Você pode usar variáveis auxiliares (const, let), laços (map, filter), condicionais e todos os métodos nativos do JavaScript:

function transform(webhook) {  
  const cliente = webhook.payload.user;

  // Normaliza o telefone (apenas dígitos)  
  const telefoneFormatado = cliente.telefone.replace(/\\D/g, "");

  // Usa um parâmetro informado no momento do uso  
  const mensagem = webhook.variables.mensagem;

  return {  
    url: webhook.url,  
    headers: {  
      ...webhook.headers,  
      "Content-Type": "application/json"  
    },  
    payload: {  
      contact: {  
        name: cliente.nome,  
        email: cliente.email,  
        phone: telefoneFormatado,  
      },  
	 message = mensagem,  
      timestamp: new Date().toISOString()  
    }  
  };  
}

📘

Apoio na escrita

O editor oferece snippets pré-prontos (Sistema, Payload, Variáveis, Headers) para inserir rapidamente as propriedades de entrada, além da opção de adicionar variáveis. Use-os para descobrir os campos disponíveis no objeto webhook.

Testes

Antes de ativar, valide a definição na própria interface. Há dois testes:

Para o teste, você informa valores de teste para as variáveis usadas na transformação.

O painel de resultado retorna:

• URL
• Payload size
• Timing
• Call duration
• Método HTTP
• Response code
• Request headers
• Request payload
• Response headers
• Response body

Limites e comportamento

🚧

Tratamento de falhas

Ainda não há fila de retentativa nem reprocessamento automático de execuções com falha.

Ciclo de vida e status

❗️

Edição reflete em tempo real

Ao confirmar a edição de um webhook em uso, todas as requisições posteriores passam a executar com a nova configuração imediatamente, sem janela de transição. Antes de editar, verifique em quais registros o webhook é utilizado.

Rastreio no perfil do consumidor

A cada disparo, a Dito registra um evento no perfil do consumidor, permitindo auditar que a notificação foi enviada ao provedor externo. O evento carrega metadados do disparo, como canal, provedor e identificadores da notificação/disparo.

{  
  "action": "sent-to-provider-webhook-notification",  
  "properties": {  
    "custom_data": {  
      "canal": "webhook",  
      "provedor": "webhook",  
      "id_disparo": "EXQ7G877X7VW2F0SCHV4E78",  
      "id_notificacao": "ABCD123456",  
      "nome_notificacao": "Campanha de webhook",  
      "notification_revision_id": "EXQ7G877X7VW2F09SCHX04A0"  
    }  
  }  
}

Modelo de execução