Configure Webhooks via API

Overview

The webhook configuration API allows you to programmatically define where your application will receive PIX event notifications. This eliminates the need to contact support to configure webhooks.

Changes to webhook configuration are applied immediately. Subsequent transactions will use the configured URLs.

Authentication

Requires an Account Bearer token in the Authorization header.

Authorization: Bearer {account_token}

The token must be obtained through the authentication endpoint using your client certificate.

Parameters

stringobrigatorio

HTTPS URL of your webhook endpoint.

Requirements:

Must use HTTPS protocol (HTTP is not accepted)
Must be a valid and accessible URL

Example: https://api.example.com/webhooks/pix

stringobrigatorio

Event type to receive notifications for.

Possible values:

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

array

Custom headers for your endpoint authentication (maximum 5).

Each item must have:

key: Header name
value: Header value

Blocked headers (not allowed):

host
content-length
connection
transfer-encoding
content-type
user-agent

Request Example

curl -X POST https://api-pay.brasilbitco.in/api/webhooks \
  -H "Authorization: Bearer {account_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/pix",
    "eventType": "cash_in",
    "headers": [
      {
        "key": "Authorization",
        "value": "Bearer my-secret-token"
      },
      {
        "key": "X-Webhook-Secret",
        "value": "abc123"
      }
    ]
  }'

const response = await fetch('https://api-pay.brasilbitco.in/api/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accountToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://api.example.com/webhooks/pix',
    eventType: 'cash_in',
    headers: [
      { key: 'Authorization', value: 'Bearer my-secret-token' },
      { key: 'X-Webhook-Secret', value: 'abc123' },
    ],
  }),
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    'https://api-pay.brasilbitco.in/api/webhooks',
    headers={
        'Authorization': f'Bearer {account_token}',
        'Content-Type': 'application/json',
    },
    json={
        'url': 'https://api.example.com/webhooks/pix',
        'eventType': 'cash_in',
        'headers': [
            {'key': 'Authorization', 'value': 'Bearer my-secret-token'},
            {'key': 'X-Webhook-Secret', 'value': 'abc123'},
        ],
    },
)

print(response.json())

Response Example

{
  "success": true,
  "message": "Webhook configured successfully"
}

Multiple URLs per Event

You can register up to 3 active URLs for the same eventType. Each call to this endpoint adds a new URL to the event — the other URLs already registered remain active and are not replaced.

If you resend a URL that is already registered for that eventType, it is updated (headers and version), without creating a duplicate webhook.

When the event occurs, the notification is sent as a fan-out to all active URLs registered for that eventType. Each URL has its own delivery, retry, and idempotency — a failure on one URL does not affect the others.

When re-registering an existing URL, omitting headers or version preserves the previous values. Explicitly sending the field replaces the previous value for that field — other omitted fields remain preserved.

Error Codes

Code	Description
400	Invalid URL (not HTTPS), invalid event type, more than 5 headers, or more than 3 active URLs per event
401	Token not provided or invalid
404	Account not found
500	Internal error configuring webhook

Configuring Multiple Events

To receive notifications for multiple event types, make a call for each type:

const eventTypes = [
  'cash_in',
  'cash_out',
  'refund_in',
  'refund_out',
  'med_created',
  'med_accepted',
  'med_rejected',
];

for (const eventType of eventTypes) {
  await fetch('https://api-pay.brasilbitco.in/api/webhooks', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accountToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      url: 'https://api.example.com/webhooks/pix',
      eventType,
      headers: [
        { key: 'X-Webhook-Secret', value: 'abc123' },
      ],
    }),
  });
}

You can use the same URL for all event types and differentiate by the type field in the webhook payload.

Configure Webhooks via API

Overview

Endpoint

Authentication

Parameters

Request Example

Response Example

Multiple URLs per Event

Error Codes

Configuring Multiple Events

Next Steps

Payload Structure

Implementation

Resend Webhook

Cash-In Webhook

MED Webhooks

On this page