Criar webhook (o secret aparece UMA única vez)

POST

/api/v2/webhooks/subscriptions

Cria uma assinatura de webhook.

⚠️ O campo data.secret da resposta é exibido somente nesta chamada —
salve-o imediatamente. Ele é usado pra validar a assinatura HMAC das entregas
(ver o endpoint [Contrato] Evento entregue na sua URL). Depois disso, apenas
secret_preview (8 primeiros caracteres) fica visível. Perdeu o secret?
Delete a assinatura e crie outra.

Validações da URL:

Apenas HTTPS em produção

Host precisa resolver pra IP público — IPs privados, loopback e link-local
são bloqueados (proteção SSRF): URL bloqueada: x.x.x.x é um endereço privado ou reservado

Rate limit: 10 criações/minuto por usuário → HTTP 429.

⚠️ Atenção ao padrão de erro: validações respondem HTTP 200 com
{ok: false, code: 400, message} no body — confira ok, não o status HTTP.

Requisição

Parâmetros Header

Parâmetros Bodyapplication/json

Examples

Respostas

🟢200OK

application/json

Sucesso (com secret em claro — única exibição) ou erro de validação (ok: false, code 400 no body).

Bodyapplication/json

🟠429

Request Example

Shell

JavaScript

Java

Swift

curl --location '/api/v2/webhooks/subscriptions' \
--header 'api-key: {{api-key}}' \
--header 'Content-Type: application/json' \
--data '{
    "url": "https://erp.suaempresa.com.br/atendimento/webhook",
    "name": "Integração ERP",
    "events": [
        "ticket.created",
        "ticket.closed",
        "message.created"
    ]
}'

Response Example

200 - Criado — SALVE O SECRET AGORA

{
    "ok": true,
    "code": 200,
    "data": {
        "id": "0b6e7a3c-9a1f-4e9e-b1f2-3c4d5e6f7a8b",
        "name": "Integração ERP",
        "description": "Integração ERP",
        "url": "https://erp.suaempresa.com.br/atendimento/webhook",
        "events": [
            "ticket.created",
            "ticket.closed",
            "message.created"
        ],
        "filters": {},
        "is_active": true,
        "secret_preview": "3f9a1c2b…",
        "secret": "3f9a1c2b7e8d4a5f6b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a",
        "created_by": 1234,
        "created_at": "2026-06-11T14:00:00.000Z",
        "updated_at": "2026-06-11T14:00:00.000Z"
    },
    "message": "Salve o secret — ele não será exibido novamente"
}

Modificado em 2026-11-04 02:53:16

Página anterior

Listar webhooks cadastrados

Próxima página

Testar conectividade de uma URL