Webhooks

Webhooks let your application receive HTTP POST requests whenever specific events happen on your BeInfi account — such as a payment completing, a refund being issued, or a new order being placed.

Setting up webhooks

1. Go to Settings > Developer > Webhooks.
2. Click Add Endpoint.
3. Enter your endpoint URL (must be HTTPS).
4. Select the events you want to subscribe to.
5. Click Save.

BeInfi sends a test ping to verify your endpoint is reachable. Your server must respond with a 200 status code within 5 seconds.

Event types

Event	Description
payment.completed	A PIX payment was successfully received.
payment.refunded	A payment was refunded to the buyer.
payment.expired	A payment link expired without being paid.
order.created	A new marketplace order was placed.
order.fulfilled	An order was marked as fulfilled.
listing.published	A marketplace listing was published.
listing.removed	A listing was removed from the marketplace.

Payload format

Every webhook delivery includes a JSON payload with the event type, timestamp, and relevant data:

{
  "id": "evt_xyz789",
  "type": "payment.completed",
  "created_at": "2025-06-15T14:30:00Z",
  "data": {
    "payment_id": "pay_abc123",
    "amount_cents": 5000,
    "currency": "BRL",
    "payment_link_id": "pl_def456",
    "payer_email": "buyer@example.com"
  }
}

Verifying signatures

Every webhook request includes an X-BeInfi-Signature header. Verify this signature to ensure the request came from BeInfi and was not tampered with.

import crypto from 'crypto';

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Your webhook signing secret is available in Settings > Developer > Webhooks.

Retry policy

If your endpoint returns a non-2xx status code or times out, BeInfi retries the delivery with exponential backoff:

• Retry 1: after 1 minute
• Retry 2: after 5 minutes
• Retry 3: after 30 minutes
• Retry 4: after 2 hours
• Retry 5: after 24 hours

After 5 failed attempts, the event is marked as failed. You can manually retry failed deliveries from the dashboard.

Best practices

• Always verify the webhook signature before processing.
• Respond with 200 quickly and process the event asynchronously.
• Make your webhook handler idempotent — the same event may be delivered more than once.
• Log all incoming webhook payloads for debugging.