Webhooks

Configure endpoints para receber notificações quando eventos acontecem no Sonar. Webhooks permitem integrar o Sonar com sistemas externos em tempo real.

GET /v1/webhooks

Lista todos os webhook endpoints do time.

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
`page`	number	1	Página atual
`limit`	number	20	Itens por página (máx: 100)
`active`	string	—	Filtrar: `true` ou `false`

Request

curl -X GET "https://app.sonar.marketing/api/v1/webhooks" \
  -H "Authorization: Bearer snr_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Notificação CRM",
      "slug": "notificacao-crm",
      "is_active": true,
      "target_pipeline_id": null,
      "target_column_id": null,
      "field_mapping": {},
      "created_at": "2026-02-15T10:30:00Z",
      "updated_at": "2026-02-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "pages": 1
  }
}

POST /v1/webhooks

Cria um novo webhook endpoint.

Request Body

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do webhook
`slug`	string	Não	Slug único (gerado automaticamente se omitido)
`is_active`	boolean	Não	Ativo? (padrão: true)
`target_pipeline_id`	string	Não	UUID do pipeline de destino
`target_column_id`	string	Não	UUID da coluna de destino
`field_mapping`	object	Não	Mapeamento de campos

Request

curl -X POST https://app.sonar.marketing/api/v1/webhooks \
  -H "Authorization: Bearer snr_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Integração RD Station",
    "target_pipeline_id": "pipeline-uuid"
  }'

Response (201)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Integração RD Station",
    "slug": "integracao-rd-station",
    "is_active": true,
    "target_pipeline_id": "pipeline-uuid",
    "target_column_id": null,
    "field_mapping": {},
    "secret_token": "whsec_a1b2c3d4e5f6...",
    "created_at": "2026-02-15T10:30:00Z",
    "updated_at": "2026-02-15T10:30:00Z"
  }
}

Importante

O secret_token é exibido apenas na criação. Guarde-o em local seguro — ele é usado para validar as requisições recebidas no seu endpoint.

GET /v1/webhooks/:id

Busca um webhook por UUID.

PUT /v1/webhooks/:id

Atualiza campos. Aceita: name, is_active, target_pipeline_id, target_column_id, field_mapping.

DELETE /v1/webhooks/:id

Exclui permanentemente o webhook endpoint.

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "deleted": true
  }
}

Validação de Requisições

Use o secret_token para validar que as requisições vêm do Sonar:

import crypto from 'crypto';

function verifyWebhook(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return hash === signature;
}

O Sonar envia o header X-Webhook-Signature com o HMAC-SHA256 do payload.

Webhooks

On this page