Inscrições

Gerenciamento de webhooks da API key.

Visão geral

Configure URLs externas que recebem notificações em tempo real para os eventos da API key (depósitos pagos, saques enviados, etc). A gestão de webhooks acontece no painel autenticado via JWT.

Autenticação

Endpoints requerem JWT Bearer do painel autenticado (não chave de API). Cada webhook é vinculado a uma API key específica via parâmetro de path :keyId.

Criar

POST /api-keys/{keyId}/webhooks

Rate limit: 15 req/min, burst 3/5s

Cria uma nova subscription. Body deve conter url (HTTPS obrigatório) e events (array de strings). O secret HMAC retornado aparece UMA única vez na resposta — salve em local seguro, não é exibido novamente.

Exemplo de requisição

bash

curl -X POST https://api.deflow.exchange/api-keys/{keyId}/webhooks \
  -H "Authorization: Bearer <painel JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meusite.com/webhook",
    "events": ["deposit:paid", "withdraw:sent"]
  }'

Exemplo de resposta da requisição

json

{
  "data": {
    "id": "67234abc...",
    "url": "https://meusite.com/webhook",
    "events": [
      "deposit:paid",
      "withdraw:sent"
    ],
    "secret": "whsec_...",
    "status": "active",
    "createdAt": "2026-05-15T12:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-05-15T12:00:00.000Z"
  }
}

Listar

GET /api-keys/{keyId}/webhooks

Rate limit: 30 req/min, burst 5/5s

Lista todas as subscriptions vinculadas à API key. O campo secret nunca é retornado em listagens; use rotate-secret se precisar de um novo.

Exemplo de requisição

bash

curl https://api.deflow.exchange/api-keys/{keyId}/webhooks \
  -H "Authorization: Bearer <painel JWT>"

Exemplo de resposta da requisição

json

{
  "data": [
    {
      "id": "67234abc...",
      "url": "https://meusite.com/webhook",
      "events": [
        "deposit:paid",
        "withdraw:sent"
      ],
      "status": "active",
      "createdAt": "2026-05-15T12:00:00.000Z"
    }
  ],
  "meta": {
    "timestamp": "2026-05-15T12:00:00.000Z"
  }
}

Atualizar

PATCH /api-keys/{keyId}/webhooks/{subscriptionId}

Rate limit: 15 req/min, burst 3/5s

Atualiza url, events ou status (active|disabled). Campos omitidos permanecem inalterados. Não rotaciona o secret.

Exemplo de requisição

bash

curl -X PATCH https://api.deflow.exchange/api-keys/{keyId}/webhooks/{subscriptionId} \
  -H "Authorization: Bearer <painel JWT>" \
  -H "Content-Type: application/json" \
  -d '{"events": ["deposit:paid"], "status": "active"}'

Exemplo de resposta da requisição

json

{
  "data": {
    "id": "67234abc...",
    "url": "https://meusite.com/webhook",
    "events": [
      "deposit:paid"
    ],
    "status": "active",
    "updatedAt": "2026-05-15T12:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-05-15T12:00:00.000Z"
  }
}

Deletar

DELETE /api-keys/{keyId}/webhooks/{subscriptionId}

Rate limit: 10 req/min, burst 3/5s

Remove a subscription. Retorna 204 No Content. Operação irreversível — entregas em andamento são canceladas.

bash

curl -X DELETE https://api.deflow.exchange/api-keys/{keyId}/webhooks/{subscriptionId} \
  -H "Authorization: Bearer <painel JWT>"