Cadastrar um endpoint

Cadastra um endereço para receber eventos e devolve o segredo UMA única vez. É esse segredo que assina cada entrega.

POSThttps://api.navenaut.com/webhooks-out/endpoints

Autenticação

A sessão do painel autentica esta rota, e ela é lida de forma autoritativa: não há parâmetro em que o chamador aponte para outra conta.

Esta rota não exige escopo nomeado — o que não quer dizer que ela seja aberta: sem a credencial acima ela recusa.

Exige sessão de vendedor. Todo endpoint lido ou escrito é escopado pela sessão: o identificador na URL nunca alcança o endpoint de outro vendedor.

Parâmetros

Corpo da requisição

application/json.

Campo	Tipo	Descrição
`apiKey`	texto	A chave que o seu servidor exige para aceitar a chamada. Opcional. Fica cifrada e não volta em nenhuma resposta.
`authHeader`	texto	O cabeçalho que leva a chave. Sem ele, a chave vai em `Authorization: Bearer` seguido da chave; com ele, pura no cabeçalho escolhido.
`eventTypes`	arranjo de um de: `account.migration_scheduled`, `advance.credited`, `charge.cancelled`, `debt.settled`, `funds.held`, `funds.released`, `kyc.updated`, `payout.failed`, `payout.paid`, `payout.partially_settled`, `payout.reversed`, `sale.chargeback`, `sale.disputed`, `sale.med_returned`, `sale.paid`, `sale.refunded`, `withdrawal.completed`	Os tipos de evento que este endpoint assina. Entregamos só o que está nesta lista.
`name`obrigatório	texto	O nome que você dá a este destino. Só aparece no painel.
`productIds`obrigatório	arranjo de texto (uuid)	Os produtos cujas vendas este destino recebe. Obrigatório, com ao menos um produto da sua conta.
`url`obrigatório	texto	Para onde entregar. Endereço de rede interna é recusado: a entrega sai para a internet pública.

{
  "apiKey": "valor-de-exemplo-nao-use",
  "authHeader": "exemplo",
  "eventTypes": [
    "account.migration_scheduled"
  ],
  "name": "Meu servidor de pedidos",
  "productIds": [
    "0f2a4e6c-91c4-4e1b-9a3d-5b7c2e8f4a06"
  ],
  "url": "https://loja.exemplo.com.br/webhooks"
}

Respostas

200 · sucesso

{
  "active": true,
  "eventTypes": [
    "exemplo"
  ],
  "id": "0f2a4e6c-91c4-4e1b-9a3d-5b7c2e8f4a06",
  "name": "Loja Exemplo",
  "productIds": [
    "exemplo"
  ],
  "secret": "valor-de-exemplo-nao-use"
}

Endpoint cadastrado, com o segredo no corpo. Cada entrega chega com X-Naut-Signature (sha256= mais o HMAC-SHA256 de timestamp.corpoCru) e X-Naut-Timestamp em segundos. Verifique sobre o corpo CRU, recuse timestamp fora de 300 s ANTES de comparar o HMAC, e compare em tempo constante. A receita pronta, por plataforma, está em docs/webhook-out-verification-recipe.md. O corpo de sale.paid traz chargeId, que é o mesmo identificador devolvido por POST /v1/charges: é por ele que você liga o aviso de pagamento ao pedido que criou, sem consultar cobrança pendente nenhuma.

409 · conflito

Já existe um endpoint com essa URL nesta conta.

422 · corpo inválido

A URL, os produtos, o cabeçalho ou a lista de eventos não passou na validação.

Erros desta rota

Status	Código	Quando	O que fazer
409	`WEBHOOK_ENDPOINT_DUPLICATE`	Já existe um endpoint com essa mesma URL nesta conta. Cadastrar o segundo faria cada evento chegar duas vezes no mesmo lugar, com dois segredos diferentes.	Use o endpoint que já existe, e altere os tipos assinados dele por `PATCH /webhooks-out/endpoints/{endpointId}` se for isso que você queria. Nenhum endpoint novo foi criado, e nenhum segredo novo foi emitido.
422	`WEBHOOK_ENDPOINT_URL_NOT_ALLOWED`	A URL não é um destino para onde a entrega possa sair: endereço de rede interna, esquema que não é HTTP, ou nome que não resolve para fora. A entrega sai da nossa rede para a internet pública, e um endereço interno faria a chamada voltar para dentro de casa.	Cadastre um endereço público e alcançável e reenvie. Nada foi cadastrado.
422	`WEBHOOK_ENDPOINT_PRODUCT_INVALID`	A lista de produtos traz um produto que não é desta conta. O destino só recebe vendas de produtos seus.	Escolha só produtos da sua conta, na listagem de produtos, e reenvie. Nada foi gravado.
422	`WEBHOOK_AUTH_HEADER_NOT_ALLOWED`	O cabeçalho escolhido para a chave de API é um dos reservados: os de assinatura da Naut (`X-Naut-Signature`, `X-Naut-Timestamp`) ou os do transporte, como `Content-Type` e `Host`.	Use `Authorization` ou outro nome para o cabeçalho da chave e reenvie. Nada foi gravado.

Os códigos são estáveis e fazem parte do contrato. A lista completa, com todos os vocabulários, está na tabela de erros.

Próximo passo

Ver o histórico de entregas