Webhooks

Endpoints para gerenciar os webhooks da sua conta. Para os payloads, headers e a verificação de assinatura, veja o guia de webhooks.

Método	Endpoint	Descrição
POST	/api/webhooks	Registra um endpoint
GET	/api/webhooks	Lista os endpoints registrados
POST	/api/webhooks/{magic_id}/test	Dispara uma entrega de teste assinada
DELETE	/api/webhooks/{magic_id}	Remove um endpoint

Registrar

POST /api/webhooks

Campo	Tipo	Obrigatório	Descrição
url	string	Sim	URL HTTPS do seu servidor
events	string[]	Sim	Eventos assinados: transaction, withdraw, dispute

Todos os eventos

POST /api/webhooks — transaction, withdraw e dispute

curl --request POST \
  --url https://api.avexus.app/api/webhooks \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "url": "https://seu-servidor.com.br/webhooks/avexus",
    "events": ["transaction", "withdraw", "dispute"]
  }'

Só transaction

POST /api/webhooks — somente transaction

curl --request POST \
  --url https://api.avexus.app/api/webhooks \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "url": "https://seu-servidor.com.br/webhooks/cobrancas",
    "events": ["transaction"]
  }'

Só withdraw

POST /api/webhooks — somente withdraw

curl --request POST \
  --url https://api.avexus.app/api/webhooks \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "url": "https://seu-servidor.com.br/webhooks/saques",
    "events": ["withdraw"]
  }'

201 — Webhook created

{
  "code": 201,
  "content": {
    "magic_id": "wh_03UdoKvLNLHg",
    "url": "https://seu-servidor.com.br/webhooks/avexus",
    "secret": "whsec_2f1f9e5cbe7b4b3c9a6d",
    "events": ["transaction", "withdraw", "dispute"],
    "active": true,
    "created_at": "2026-07-24T18:38:25.688Z",
    "updated_at": "2026-07-24T18:38:26.703Z"
  },
  "message": "Webhook created",
  "timestamp": "2026-07-24T18:38:26.703Z"
}

Guarde o secret agora

O secret (whsec_…) aparece apenas nesta resposta. Na listagem ele vem mascarado (whsec_********). É com ele que você valida a assinatura HMAC SHA256 das entregas — sem ele, não há como distinguir uma entrega nossa de um POST qualquer.

Testar

POST /api/webhooks/{magic_id}/test

Enfileira uma entrega sintética e assinada para o endpoint — o jeito de validar a integração de ponta a ponta sem esperar um pagamento real.

Campo	Tipo	Descrição
event	string	Opcional. Qual formato enviar: transaction, withdraw ou dispute.

POST /api/webhooks/{magic_id}/test

curl --request POST \
  --url https://api.avexus.app/api/webhooks/wh_03UdoKvLNLHg/test \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --data '{ "event": "transaction" }'

202 — Test webhook queued

{
  "code": 202,
  "content": {
    "delivery_id": "0f2c9a41-6c58-4d0e-9a3f-6d5a1c7b2e88",
    "magic_id": "wh_03UdoKvLNLHg",
    "url": "https://seu-servidor.com.br/webhooks/avexus",
    "event": "transaction",
    "test": true
  },
  "message": "Test webhook queued",
  "timestamp": "2026-07-24T18:38:26.703Z"
}

Dica

O corpo da entrega de teste tem a mesma forma de um evento real e é assinado com o mesmo secret — dá para exercitar a sua verificação de assinatura com ele. O campo test: true na resposta identifica a entrega no painel.

Listar

GET /api/webhooks

GET /api/webhooks

curl --request GET \
  --url https://api.avexus.app/api/webhooks \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'

Os secret vêm mascarados:

200 — Webhooks returned

{
  "code": 200,
  "content": [
    {
      "magic_id": "wh_03UdoKvLNLHg",
      "url": "https://seu-servidor.com.br/webhooks/avexus",
      "secret": "whsec_********",
      "events": ["transaction", "withdraw", "dispute"],
      "active": true,
      "created_at": "2026-07-24T18:38:25.688Z",
      "updated_at": "2026-07-24T18:38:26.703Z"
    }
  ],
  "message": "Webhooks returned",
  "timestamp": "2026-07-24T18:38:26.703Z"
}

Remover

DELETE /api/webhooks/{magic_id}

DELETE /api/webhooks/{magic_id}

curl --request DELETE \
  --url https://api.avexus.app/api/webhooks/wh_03UdoKvLNLHg \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>'

200 — Webhook deleted

{
  "code": 200,
  "content": { "magic_id": "wh_03UdoKvLNLHg" },
  "message": "Webhook deleted",
  "timestamp": "2026-07-24T18:38:26.703Z"
}

Veja também

• Receber webhooks — payloads, headers e verificação HMAC.
• Cobranças — reenvio com resend=true.
• Códigos de erro.