Webhooks

​

Setting up webhooks

1. Go to Settings > Webhooks in the dashboard.
2. Click Add webhook and enter your endpoint URL. The URL must use HTTPS.
3. Select the events you want to receive.
4. Save the generated secret somewhere safe — it is shown only once and is required to verify incoming requests.

​

Event types

​

Webhook payload

{
  "id": "5d0f8b6e-3a02-4f5b-9e1c-7c6a4a1b8c9d",
  "txId": "PAY3F2A8B9C4E6D1F5A7B3C8D2E9F4A6B1C",
  "status": "PAID",
  "amount": 49.9,
  "paidAt": "2026-06-06T12:00:00.000Z",
  "endToEndId": "E000000022026060612000abc1234def",
  "payer": {
    "name": "Maria Silva",
    "document": "39053344705",
    "documentType": "CPF",
    "institutionName": "Banco Example S.A.",
    "institutionIspb": "00000000"
  }
}

{
  "withdrawalId": "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "txId": "WIT1746280868443K3F9Q",
  "netAmount": 100,
  "status": "COMPLETED",
  "endToEndId": "E000000022026060612050def5678abc",
  "recipient": {
    "name": "João Souza",
    "document": "52998224725",
    "institutionName": "Banco Example S.A.",
    "institutionIspb": "00000000",
    "branch": "0001",
    "account": "123456"
  }
}

​

Body per event type

• How a payment is identified varies by event. PAYMENT_PAID carries both id (the payment UUID) and txId. PAYMENT_CONFIRMED, PAYMENT_CHARGEBACK and some PAYMENT_EXPIRED / PAYMENT_CANCELLED deliveries carry only txId. PAYMENT_REFUNDED, PAYMENT_REFUND_FAILED, MED_RECEIVED and MED_RESOLVED carry only paymentId and no txId at all. Key your lookup on whichever of the three is present, not on one of them.
• Absent means null, except for a few keys that vanish. Most optional fields arrive as an explicit null — paidAt, endToEndId, payer, recipient all do. A small set is dropped from the JSON instead: failureReason on WITHDRAWAL_SENT, and source, providerMedId, refundId and amount on the MED and refund paths that do not set them. Read the value with a null-safe accessor rather than testing key presence.
• The dashboard “resend” button sends a thinner body. A delivery you trigger by hand from a transaction in the dashboard carries a generic { id, txId, status, amount } shape (plus netAmount for withdrawals) — not the per-event body documented here — and gets a fresh X-Webhook-Delivery-Id. Note it keys the resource as id, not as paymentId / withdrawalId. Do not treat a resend as byte-identical to the original delivery.
• txId formats. Payments are PAY + 32 uppercase hex characters. Withdrawals are WIT + a millisecond timestamp + 5 uppercase alphanumerics (e.g. WIT1746280868443K3F9Q). Refunds vary by origin. Treat txId as an opaque string; do not parse or validate its shape.

​

Sandbox

​

Request headers

​

Verifying signatures

expected = "v1=" + hex(HMAC_SHA256(secret, timestamp + "." + raw_body))

1. Read X-Webhook-Timestamp and X-Webhook-Signature from the headers.
2. Compute the expected signature using your stored secret and the raw, unparsed request body.
3. Compare in constant time. Reject if they don’t match.
4. Reject any request whose timestamp is more than 300 seconds off the current time. This is our recommended replay window; pick your own if your clocks or queues need more slack.

import crypto from "crypto";

const SKEW_SECONDS = 300;

function verifyWebhook(rawBody, headers, secret) {
  const ts = headers["x-webhook-timestamp"];
  const sig = headers["x-webhook-signature"];
  if (!ts || !sig) return false;

  const drift = Math.abs(Math.floor(Date.now() / 1000) - parseInt(ts, 10));
  if (drift > SKEW_SECONDS) return false;

  const expected = "v1=" + crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(sig);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const rawBody = req.body.toString("utf8");
  if (!verifyWebhook(rawBody, req.headers, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const eventType = req.headers["x-webhook-event"];
  const deliveryId = req.headers["x-webhook-delivery-id"];
  const body = JSON.parse(rawBody);

  if (alreadyProcessed(deliveryId)) return res.status(200).send("OK");

  switch (eventType) {
    case "PAYMENT_PAID":
      console.log(body.txId, body.amount, body.payer?.document ?? null);
      break;
    case "WITHDRAWAL_SENT":
      console.log(body.txId, body.recipient?.document ?? null);
      break;
    case "WITHDRAWAL_FAILED":
      console.log(body.txId, body.failureReason);
      break;
  }

  res.status(200).send("OK");
});

import hmac
import hashlib
import time
from flask import Flask, request

app = Flask(__name__)
SKEW_SECONDS = 300

def verify_webhook(raw_body: bytes, headers, secret: str) -> bool:
    ts = headers.get("X-Webhook-Timestamp", "")
    sig = headers.get("X-Webhook-Signature", "")
    if not ts or not sig:
        return False

    if abs(int(time.time()) - int(ts)) > SKEW_SECONDS:
        return False

    expected = "v1=" + hmac.new(
        secret.encode(),
        f"{ts}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(sig, expected)

@app.post("/webhook")
def webhook():
    if not verify_webhook(request.data, request.headers, WEBHOOK_SECRET):
        return "Invalid signature", 401

    event_type = request.headers.get("X-Webhook-Event")
    delivery_id = request.headers.get("X-Webhook-Delivery-Id")
    body = request.get_json()

    if already_processed(delivery_id):
        return "OK", 200

    if event_type == "PAYMENT_PAID":
        print(body["txId"], body["amount"], (body.get("payer") or {}).get("document"))
    elif event_type == "WITHDRAWAL_SENT":
        print(body["txId"], (body.get("recipient") or {}).get("document"))
    elif event_type == "WITHDRAWAL_FAILED":
        print(body["txId"], body.get("failureReason"))

    return "OK", 200

​

Delivery semantics

• At-least-once delivery. The same event may arrive more than once. Treat X-Webhook-Delivery-Id as the deduplication key. If you’ve processed a delivery id before, return 200 and skip the side effects.
• Order is not guaranteed. Deliveries are dispatched in parallel; under retry, a PAYMENT_REFUNDED may arrive before its prior PAYMENT_PAID. Always reconcile against the resource state in the body’s status field, not against the order of arrival.
• Synchronous timeout: 10 seconds. Return 2xx within 10 seconds. Process work asynchronously if you need longer.
• Redirects are not followed. Your endpoint must respond directly.

​

Retry behavior

• the configured retry budget for the endpoint is exhausted (capped at 24 attempts regardless of configuration);
• the delivery is older than 72 hours;
• the endpoint has been suspended.

​

Automatic endpoint suspension

• a long run of consecutive failed deliveries; or
• a sustained failure rate over a rolling window, once enough attempts have been observed to be meaningful.

1. it is deactivated and receives no new events;
2. every delivery still queued for it is moved to FAILED;
3. everyone on the account with developer access is notified in-app and by email, with the endpoint URL, the reason, and the last HTTP status and response excerpt we saw.

​

Reactivating a suspended endpoint

POST /app/companies/{companyId}/webhooks/{webhookId}/reactivate

​

Best practices

• Verify before trusting. Always validate the X-Webhook-Signature and the X-Webhook-Timestamp skew.
• Return 200 quickly. Acknowledge receipt synchronously and do business logic in a background job.
• Deduplicate by delivery id. The same event can be delivered more than once — X-Webhook-Delivery-Id is stable across retries and replays.
• Don’t rely on order. Use the body’s status field to decide what to do, not the sequence of arrivals.
• Switch on the header. X-Webhook-Event is the only place the event name appears. The body has no type field.
• Use HTTPS. Webhook endpoints must use HTTPS.
• Don’t log the secret. Treat the webhook secret like an API key.