Webhooks

GET    {BASE_URL}/api-v1-webhooks      # lista
POST   {BASE_URL}/api-v1-webhooks      # cria
DELETE {BASE_URL}/api-v1-webhooks/:id  # remove

Use os endereços acima — são os que respondem hoje. A API está migrando para um endereço único ({BASE_URL}/api-v1/webhooks), que ainda não foi publicado: enquanto isso, qualquer chamada para ele devolve 404 not_found. Quando entrar no ar, esta página muda junto, e os endereços acima continuam valendo.

Escopo: webhooks:manage — um só, cobre leitura e escrita.

Permissão única webhooks:manage (não é read/write). DELETE desativa a assinatura e responde 204 — o histórico dela não é apagado.

Campos

Campo	Tipo	Escrita	Notas
`id`	uuid	somente leitura
`event_types`	lista de textos	criar: obrigatório, editar: não	Só valores da lista de eventos suportados. mínimo 1 item.
`target_url`	string	criar: obrigatório, editar: não	Exige HTTPS e host público (anti-SSRF). formato url; de 1 a 2048 caracteres.
`secret`	string	somente leitura	Devolvido UMA vez, na criação, e nunca mais. Assina o corpo (HMAC). Devolvido só na resposta de criação — não aparece na listagem. Campo montado pela API (não é coluna direta).
`is_active`	boolean	somente leitura
`failure_count`	number	somente leitura
`last_success_at`	datetime	somente leitura
`last_failure_at`	datetime	somente leitura
`created_at`	datetime	somente leitura

Listar webhooks

GET {BASE_URL}/api-v1-webhooks

Ordenação: created_at decrescente. Esta listagem não pagina — devolve a lista inteira.

curl "{BASE_URL}/api-v1-webhooks" \
  -H "X-API-Key: vnd_sua_chave_aqui"

{
  "data": [ /* registros */ ]
}

Criar

POST {BASE_URL}/api-v1-webhooks — escopo webhooks:manage.

Campo	Tipo	Obrigatório	Notas
`event_types`	lista de textos	Sim	Só valores da lista de eventos suportados. mínimo 1 item.
`target_url`	string	Sim	Exige HTTPS e host público (anti-SSRF). formato url; de 1 a 2048 caracteres.

curl -X POST "{BASE_URL}/api-v1-webhooks" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "event_types": ["..."], "target_url": "..." }'

Remover

DELETE {BASE_URL}/api-v1-webhooks/:id — escopo webhooks:manage.

curl -X DELETE "{BASE_URL}/api-v1-webhooks/8f3c..." \
  -H "X-API-Key: vnd_sua_chave_aqui"

Erros

HTTP	`code`	Quando
`401`	`missing_api_key` / `invalid_api_key` / `revoked_api_key`	Autenticação.
`403`	`insufficient_scope`	A chave não tem `webhooks:manage`.
`404`	`not_found`	O registro não existe neste cliente.
`422`	`validation_error`	Campo fora das regras da tabela acima.
`405`	`method_not_allowed`	Método não suportado neste endereço.
`500`	`internal_error`	Falha interna.

Catálogo completo em Erros.