Webhooks API

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

Método	Endpoint	Descrição
POST	/api/webhooks	Registra um endpoint de webhook
GET	/api/webhooks	Lista todos os webhooks registrados
DELETE	/api/webhooks/{magic_id}	Remove um webhook

Registrar webhook

POST /api/webhooks

Corpo da requisição

Campo	Tipo	Descrição
url	string	URL HTTPS do seu servidor que receberá os eventos
events	string[]	Eventos assinados: transaction, withdraw, dispute

Todos os eventos

POST /api/webhooks — transaction, withdraw e dispute

curl --request POST \
  --url https://api.simpixpagamentos.com/api/webhooks \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "url": "https://your-server.com/webhooks/hub",
    "events": ["transaction", "withdraw", "dispute"]
  }'

Somente transaction

POST /api/webhooks — somente transaction

curl --request POST \
  --url https://api.simpixpagamentos.com/api/webhooks \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "url": "https://your-server.com/webhooks/transactions",
    "events": ["transaction"]
  }'

Somente withdraw

POST /api/webhooks — somente withdraw

curl --request POST \
  --url https://api.simpixpagamentos.com/api/webhooks \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "url": "https://your-server.com/webhooks/withdrawals",
    "events": ["withdraw"]
  }'

Resposta

201 — Webhook created

{
  "code": 201,
  "content": {
    "magic_id": "wh_03UdoKvLNLHg",
    "url": "https://your-server.com/webhooks/hub",
    "secret": "whsec_2f1f9e5cbe7b4b3c9a6d",
    "events": ["transaction", "withdraw", "dispute"],
    "active": true,
    "created_at": "2025-02-19T17:15:25.688Z",
    "updated_at": "2025-02-19T17:15:26.703Z"
  },
  "message": "Webhook created",
  "timestamp": "2025-02-19T17:15:26.703Z"
}

Guarde o secret

O secret (whsec_...) é usado para calcular e validar a assinatura HMAC SHA256 do header x-webhook-signature. Armazene-o com segurança — veja a verificação de assinatura no guia de webhooks.

Listar webhooks

GET /api/webhooks

GET /api/webhooks — Listar

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

Remover webhook

DELETE /api/webhooks/{magic_id}

DELETE /api/webhooks/{magic_id} — Remover

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