Configure account webhooks

Route temporarily disabled. This route is not registering webhooks at the moment: it responds 200 with success: false and the message "Rota desativada", without persisting anything. In the meantime, register and manage your webhooks in the dashboard (https://app.ntxpay.com), under Settings → Webhooks. Webhook notifications keep being delivered normally.

POST /api/webhooks

POST https://api.ntxpay.com/api/webhooks

Requires a Bearer token in the Authorization header. See Generate Token to obtain one.

Adds a webhook URL for a specific event type (up to 3 active URLs per event). If the same URL is already registered for that event type, it is updated (headers and version) — the other registered URLs are not affected. On trigger, the notification is sent as a fan-out to all active URLs for the event.

Authentication

Requires a Bearer token in the Authorization header.

Available Events

Event	Description
`cash_in`	PIX received
`cash_out`	PIX sent
`refund_in`	Refund of received payment (refund requested)
`refund_out`	Refund received
`med_created`	MED (Special Refund Mechanism) opened against a transaction
`med_accepted`	MED refund request approved
`med_rejected`	MED refund request rejected

Request Body

Field	Type	Required	Description
`url`	string	Yes	HTTPS URL of the endpoint that will receive the webhooks
`eventType`	string	Yes	Event type: `cash_in`, `cash_out`, `refund_in`, `refund_out`, `med_created`, `med_accepted`, `med_rejected`
`headers`	array	No	Custom headers for authentication (maximum 5). Blocked headers: `host`, `content-length`, `connection`, `transfer-encoding`, `content-type`, `user-agent`
`headers[].key`	string	Yes	Header name
`headers[].value`	string	Yes	Header value

{
  "url": "https://api.example.com/webhooks/pix",
  "eventType": "cash_in",
  "headers": [
    { "key": "Authorization", "value": "Bearer token123" },
    { "key": "X-Webhook-Secret", "value": "abc123" }
  ]
}

Code Examples

cURL

curl -X POST "https://api.ntxpay.com/api/webhooks" \
  -H "Authorization: Bearer $NTXPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://api.example.com/webhooks/pix",
  "eventType": "cash_in",
  "headers": [
    { "key": "Authorization", "value": "Bearer token123" },
    { "key": "X-Webhook-Secret", "value": "abc123" }
  ]
}'

const axios = require('axios');

const response = await axios.post('https://api.ntxpay.com/api/webhooks',
  {
  "url": "https://api.example.com/webhooks/pix",
  "eventType": "cash_in",
  "headers": [
    { "key": "Authorization", "value": "Bearer token123" },
    { "key": "X-Webhook-Secret", "value": "abc123" }
  ]
},
  {
    headers: {
      'Authorization': `Bearer ${process.env.NTXPAY_TOKEN}`,
      'Content-Type': 'application/json',
    },
  }
);
console.log(response.data);

import os, requests

response = requests.post(
    'https://api.ntxpay.com/api/webhooks',
    headers={
        'Authorization': f'Bearer {os.environ["NTXPAY_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
  "url": "https://api.example.com/webhooks/pix",
  "eventType": "cash_in",
  "headers": [
    { "key": "Authorization", "value": "Bearer token123" },
    { "key": "X-Webhook-Secret", "value": "abc123" }
  ]
},
)
print(response.json())

$ch = curl_init('https://api.ntxpay.com/api/webhooks');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('NTXPAY_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "url": "https://api.example.com/webhooks/pix",
  "eventType": "cash_in",
  "headers": [
    { "key": "Authorization", "value": "Bearer token123" },
    { "key": "X-Webhook-Secret", "value": "abc123" }
  ]
}',
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

String body = """
    {
      "url": "https://api.example.com/webhooks/pix",
      "eventType": "cash_in",
      "headers": [
        { "key": "Authorization", "value": "Bearer token123" },
        { "key": "X-Webhook-Secret", "value": "abc123" }
      ]
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.ntxpay.com/api/webhooks"))
    .header("Authorization", "Bearer " + System.getenv("NTXPAY_TOKEN"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response (200)

Field	Type	Description
`success`	boolean	Indicates whether the operation was successful
`message`	string	Descriptive message of the result

{
  "success": true,
  "message": "Webhook configurado com sucesso"
}

Errors

Status	Description
400	Invalid data (URL is not HTTPS, invalid event type, more than 5 headers, or more than 3 active URLs per event)
401	Missing or invalid token
404	Account not found
500	Internal error configuring webhook