Criar um webhook

POST

/webhooks

const url = 'https://dattacrm.com.br/api/v1/webhooks';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"targetUrl":"example","events":["lead.created"],"filters":{"additionalProperty":{"additionalProperty":["example"]}},"name":"example","ignoreOwnChanges":true}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://dattacrm.com.br/api/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "targetUrl": "example", "events": [ "lead.created" ], "filters": { "additionalProperty": { "additionalProperty": [ "example" ] } }, "name": "example", "ignoreOwnChanges": true }'

Cria um webhook: o CRM passa a avisar a URL informada a cada evento escolhido, no formato padrão. Devolve o webhook e o segredo de assinatura, que aparece só nesta resposta. Por padrão o webhook ignora o que esta mesma chave causar, para o n8n não se disparar em laço; isso cobre só as mudanças feitas diretamente pela chave: o que uma automação do CRM fizer depois, em reação a essa mudança (ex.: etiqueta ou etapa aplicada por automação depois de uma venda), continua chegando. O webhook para de receber quando a chave que o criou é revogada (fica desligado) ou vence. Cada conta tem no máximo 50 webhooks, somando os da tela; acima disso a resposta é 409 conflict.

Authorizations

bearerAuth

Request Body^required

application/json

object

targetUrl

required

URL que recebe os avisos. Precisa ser https://, na porta 443, sem usuário e senha e sem ? nem # (ex.: https://n8n.exemplo.com/webhook/abc).

string

<= 500 characters

events

required

Eventos que disparam o webhook, de 1 a 22, sem repetir. Veja os aceitos em GET /webhooks/events.

Array<string>

>= 1 items <= 22 items

Allowed values: lead.created lead.updated lead.deleted lead.merged deal.entered_pipeline deal.stage_changed deal.won deal.lost deal.owner_changed tag.added tag.removed lead.captured form.submitted sale.created sale.paid sale.pending sale.refunded sale.chargeback sale.canceled sale.abandoned message.received media.synced

filters

Filtros por evento, ex.: { “sale.paid”: { “productId”: [“abc”] } }. Cada evento aceita só os filtros listados em GET /webhooks/events; filtro que o evento não aceita, ou de evento não assinado, é descartado sem erro.

object

key

additional properties

Filtros deste evento, por nome de filtro.

object

key

additional properties

Valores aceitos para o filtro, até 200.

Array<string>

<= 200 items

name

Nome do webhook, de 1 a 80 caracteres. Sem ele, usa “API · ” seguido do nome da chave.

string

>= 1 characters <= 80 characters

ignoreOwnChanges

Quando verdadeiro (padrão), o webhook não avisa sobre o que esta mesma chave de API causar, evitando que um fluxo do n8n se dispare sozinho em laço.

boolean

default: true

Responses

201

Sucesso.

application/json

object

data

required

Webhook criado e seu segredo.

object

webhook

required

Webhook da conta: um endereço que o CRM avisa quando acontecem os eventos assinados.

object

required

Identificador do webhook.

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

name

required

Nome do webhook, como aparece na tela de destinos.

string

targetUrl

required

URL https que recebe o aviso de cada evento.

string

events

required

Eventos que disparam o webhook.

Array<string>

filters

required

Filtros por evento. Vazio quando o webhook dispara para todo evento assinado.

object

key

additional properties

Filtros do evento, por nome de filtro.

object

key

additional properties

Valores aceitos para o filtro.

Array<string>

status

required

Situação: active (entregando), paused (pausado depois de falhas seguidas) ou disabled (desligado).

string

ignoreOwnChanges

required

Verdadeiro quando o webhook não avisa sobre o que a própria chave que o criou causou.

boolean

createdByApiKeyId

required

Any of:

string
null

Identificador único (UUID).

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

createdAt

required

Quando o webhook foi criado.

string format: date-time

/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/

secret

required

Segredo de assinatura (48 caracteres hexadecimais), usado para conferir o cabeçalho x-crm-signature de cada aviso. Aparece só nesta resposta: guarde agora.

string

Example

{
  "data": {
    "webhook": {
      "id": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f",
      "createdByApiKeyId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f",
      "createdAt": "2026-10-19T12:00:00.000Z"
    }
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

X-RateLimit-Limit

integer

Máximo de requisições por janela de 60 segundos para esta chave.

X-RateLimit-Remaining

integer

Requisições restantes na janela atual.

X-RateLimit-Reset

integer

Fim da janela atual, em milissegundos desde a época Unix (epoch ms).

400

Dados inválidos na requisição (validation_error), lead novo sem lista (list_required), campo que mudou de lugar (field_moved) ou chave enviada na URL (api_key_in_url).

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

401

Chave ausente, inválida (invalid_api_key), vencida (api_key_expired) ou revogada (api_key_revoked).

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

403

A chave é somente leitura e a operação grava dados (insufficient_scope).

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

409

Conflito com o estado atual (conflict), contato oculto, cujo negócio não muda (lead_hidden), ou limite do plano atingido (plan_limit).

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

413

O corpo da requisição passa de 256 KB (payload_too_large).

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

429

Limite de requisições atingido (rate_limited). Aguarde Retry-After segundos.

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

X-RateLimit-Limit

integer

Máximo de requisições por janela de 60 segundos para esta chave.

X-RateLimit-Remaining

integer

Requisições restantes na janela atual.

X-RateLimit-Reset

integer

Fim da janela atual, em milissegundos desde a época Unix (epoch ms).

Retry-After

integer

Segundos até poder tentar de novo.

500

Erro interno (internal_error). Informe o requestId ao suporte.

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

503

O CRM está em modo somente leitura durante uma migração (maintenance). Tente de novo depois de Retry-After segundos.

application/json

Formato de erro da API.

object

error

required

object

code

required

Código estável do erro, ex.: validation_error.

string

message

required

Mensagem legível em português.

string

details

Detalhes extras, ex.: lista de campos inválidos.

requestId

required

Identificador da requisição, para suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

X-Request-Id

string

Identificador da requisição, para suporte.

Retry-After

integer

Segundos até poder tentar de novo.

Criar um webhook

Authorizations

Request Body required

Responses

201

Example

Headers

400

Example generated

Headers

401

Example generated

Headers

403

Example generated

Headers

409

Example generated

Headers

413

Example generated

Headers

429

Example generated

Headers

500

Example generated

Headers

503

Example generated

Headers

Request Body^required

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated