Endpoint: POST /integrations/webhooks/{seller_id}/webhooks/
Autenticação: token JWT ou chave de API do vendedor. Consulte Autenticação.
Cria uma nova assinatura de webhook para o vendedor. Depois de criada, o despachante envia uma requisição POST com um payload JSON para a url informada sempre que um evento cujo nome apareça (como substring, sem diferenciar maiúsculas e minúsculas) dentro da string events for emitido pela plataforma. A semântica completa de despacho e retentativas está documentada em Webhooks e Jobs.

​
Parâmetros de caminho

​
seller_id
string (uuid)
required
Vendedor ao qual este webhook pertence. Deve referenciar um vendedor existente; caso contrário a requisição é rejeitada com 400 e mensagem "Seller not found.".

​
Corpo

​
url
string
required
URL de destino. Pode ser fornecida sem esquema — o despachante adiciona https:// caso http:// ou https:// não estejam presentes.
​
secret
string
required
Segredo compartilhado. Ele é enviado de volta ao seu endpoint dentro do payload JSON ("secret": "<valor>") para que seu handler verifique que a chamada vem da plataforma. Trate-o como uma senha: a API nunca retorna este valor em GETs posteriores, portanto armazene-o do seu lado no momento da criação. Para fazer rotação, atualize o webhook com um novo valor.
​
events
string
required
Tipos de evento aos quais este webhook se inscreve. A correspondência é por substring, sem diferenciar maiúsculas e minúsculas: o despachante dispara este webhook quando o nome do evento (em minúsculas) está contido na string events (em minúsculas). O formato recomendado é uma lista separada por vírgulas com nomes canônicos.Nomes de evento emitidos atualmente:
  • transaction.update.status — uma transação finalizou, falhou ou mudou de estado e o vendedor possui webhooks configurados.
Inscrever-se em um prefixo amplo (por exemplo armazenando "transaction.") fará a correspondência com qualquer evento futuro cujo nome contenha essa substring.

​
Resposta

Retorna o webhook criado. O campo secret não é retornado.
​
id
string (uuid)
ID do webhook — armazene-o caso queira atualizar ou remover a assinatura posteriormente.
​
url
string
​
events
string
{
  "id": "5a2b6f4e-9c10-4d3a-9f17-0c2a3e4b5d61",
  "url": "https://merchant.example.com/hooks/dlpay",
  "events": "transaction.update.status"
}

​
Formato do payload enviado

Quando a plataforma chama sua url, o corpo da requisição tem este formato: 
{
  "event": "transaction.update.status",
  "secret": "<o segredo que você registrou>",
  "data": { "id": "...", "status": "...", "...": "..." }
}
Compare o campo secret com o valor que você armazenou localmente (igualdade simples de strings) para autenticar a chamada.

​
Erros

StatusQuando
400seller_id não existe ("Seller not found.") ou um campo obrigatório está ausente.
401Token JWT ou chave de API ausente ou inválida.

​
Exemplos

curl -X POST https://api.dlpay.cloud/integrations/webhooks/9b1f0d2a-2b40-4f3e-9c11-c2c0a1b3e711/webhooks/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://merchant.example.com/hooks/dlpay",
    "secret": "whk_4f2c9b1e7a884d6e",
    "events": "transaction.update.status"
  }'