Criar webhook

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

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

string

required

URL de destino. Pode ser fornecida sem esquema — o despachante adiciona https:// caso http:// ou https:// não estejam presentes.

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.

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.

string (uuid)

ID do webhook — armazene-o caso queira atualizar ou remover a assinatura posteriormente.

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

Status	Quando
`400`	`seller_id` não existe (`"Seller not found."`) ou um campo obrigatório está ausente.
`401`	Token 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"
  }'

import requests

response = requests.post(
    "https://api.dlpay.cloud/integrations/webhooks/9b1f0d2a-2b40-4f3e-9c11-c2c0a1b3e711/webhooks/",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "url": "https://merchant.example.com/hooks/dlpay",
        "secret": "whk_4f2c9b1e7a884d6e",
        "events": "transaction.update.status",
    },
)
webhook = response.json()

const response = await fetch(
  "https://api.dlpay.cloud/integrations/webhooks/9b1f0d2a-2b40-4f3e-9c11-c2c0a1b3e711/webhooks/",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://merchant.example.com/hooks/dlpay",
      secret: "whk_4f2c9b1e7a884d6e",
      events: "transaction.update.status",
    }),
  },
);
const webhook = await response.json();

Início

Autenticação e usuários

Vendedores

Vendas

Planos

Contas unificadas

Eventos

Assinaturas

Contas virtuais

Integrações do vendedor

Parâmetros de caminho

Corpo

Resposta

Formato do payload enviado

Erros

Exemplos

​Parâmetros de caminho

​Corpo

​Resposta

​Formato do payload enviado

​Erros

​Exemplos

Parâmetros de caminho

Corpo

Resposta

Formato do payload enviado

Erros

Exemplos