Skip to content
Last updated

Webhooks

ConnectPSP sends asynchronous HTTP POST events to your webhookUrl when transactions change status.

Event Structure

All events share the same envelope:

{
  "eventType": "CASHIN_PAID",
  "eventAt": "2026-03-10T14:22:18Z",
  "data": { ... }
}
FieldDescription
eventTypeIdentifies the event (see list below)
eventAtISO 8601 UTC timestamp of when the event was dispatched
dataTransaction details — mirrors the equivalent GET endpoint response

The data object for each event type always matches the response you'd get from GET /cash-in/{id} or GET /cash-out/{id}, making it easy to parse consistently.

How to Receive Webhooks

ConnectPSP will POST to your webhookUrl using:

  • Method: POST
  • Content-Type: application/json
  • Headers sent:
    • X-Connect-Signature — HMAC-SHA256 hash of the request body using your CryptoToken. Use this to verify the request is genuine.
    • X-Event-Id — Unique UUID for each delivery attempt.

Expected Response

Your endpoint must respond with HTTP 200 OK in under 5 seconds. No response body is required.

If your endpoint fails (timeout, 5xx, etc.), ConnectPSP will retry with exponential backoff.

Verifying the Signature

const crypto = require('crypto');

function isValidWebhook(rawBody, signatureHeader, cryptoToken) {
  const expected = crypto
    .createHmac('sha256', cryptoToken)
    .update(rawBody)   // rawBody = the raw request body string, NOT parsed JSON
    .digest('hex');
  return expected === signatureHeader;
}

// Express example
app.post('/webhooks/connectpsp', (req, res) => {
  const signature = req.headers['x-connect-signature'];
  const rawBody = req.rawBody; // ensure you capture raw body before JSON parsing

  if (!isValidWebhook(rawBody, signature, process.env.CRYPTO_TOKEN)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;
  // process event...
  res.status(200).send();
});

Cash-In Events

CASHIN_PAID

Fired when a PIX payment is confirmed by the banking network.

{
  "eventType": "CASHIN_PAID",
  "eventAt": "2026-03-10T11:22:18Z",
  "data": {
    "transactionId": "kk6g232xel65a0daee4dd13kk2912714964",
    "internalCode": "US7B1JQ",
    "externalReference": "order_abc123",
    "endToEndId": "E00416968202603101827cemeFscF6AG",
    "status": "PAID",
    "amount": 150.50,
    "payer": {
      "name": "João Silva",
      "document": "12345678909",
      "bankData": {
        "ispb": "00000000",
        "bank": "Banco do Brasil S.A.",
        "branch": "0001",
        "account": "123456"
      }
    },
    "requestedAt": "2026-03-10T11:20:00-03:00",
    "paidAt": "2026-03-10T11:22:15-03:00"
  }
}

CASHIN_REFUNDED

Fired after a paid Cash-In is refunded (via API, ConnectPSP panel, or a banking devolution).

{
  "eventType": "CASHIN_REFUNDED",
  "eventAt": "2026-03-11T09:30:17Z",
  "data": {
    "transactionId": "kk6g232xel65a0daee4dd13kk2912714964",
    "internalCode": "US7B1JQ",
    "externalReference": "order_abc123",
    "endToEndId": "D00416968202603101827cemeFscF6AG",
    "originalEndToEndId": "E00416968202603101827cemeFscF6AG",
    "status": "REFUNDED",
    "amount": 150.50,
    "payer": {
      "name": "João Silva",
      "document": "12345678909",
      "bankData": {
        "ispb": "00000000",
        "bank": "Banco do Brasil S.A.",
        "branch": "0001",
        "account": "123456"
      }
    },
    "requestedAt": "2026-03-10T11:20:00-03:00",
    "paidAt": "2026-03-10T11:22:15-03:00",
    "refundedAt": "2026-03-11T09:30:15-03:00"
  }
}

Cash-Out Events

CASHOUT_COMPLETED

Fired when BACEN/SPI confirms the payment was successfully settled in the payee's account.

{
  "eventType": "CASHOUT_COMPLETED",
  "eventAt": "2026-03-10T14:02:35Z",
  "data": {
    "transactionId": "dd30446e-6cc5-4664-bf3f-6b7f5e55a1a9",
    "internalCode": "IVKPRMOCDY",
    "externalReference": "withdraw_xyz789",
    "endToEndId": "E00416968202603101827cemeFscF6AG",
    "status": "COMPLETED",
    "amount": 500.00,
    "payee": {
      "name": "Maria Silva",
      "document": "12345678909",
      "destination": {
        "type": "PIX",
        "pixKeyType": "CPF",
        "pixKey": "12345678909"
      },
      "bankData": {
        "ispb": "00000000",
        "bank": "Banco do Brasil S.A.",
        "branch": "0001",
        "account": "123456"
      }
    },
    "requestedAt": "2026-03-10T14:00:00-03:00",
    "paidAt": "2026-03-10T14:02:30-03:00"
  }
}

CASHOUT_FAILED

Fired when a Cash-Out fails — e.g. invalid PIX key, frozen destination account, or banking network rejection.

{
  "eventType": "CASHOUT_FAILED",
  "eventAt": "2026-03-10T14:00:20Z",
  "data": {
    "transactionId": "dd30446e-6cc5-4664-bf3f-6b7f5e55a1a9",
    "internalCode": "IVKPRMOCDY",
    "externalReference": "withdraw_xyz789",
    "status": "FAILED",
    "amount": 500.00,
    "failure": {
      "code": "PIX_KEY_NOT_FOUND",
      "message": "The provided PIX key did not resolve to a valid account."
    },
    "payee": {
      "name": "Maria Silva",
      "document": "12345678909",
      "destination": {
        "type": "PIX",
        "pixKeyType": "CPF",
        "pixKey": "12345678909"
      }
    },
    "requestedAt": "2026-03-10T14:00:00-03:00",
    "failedAt": "2026-03-10T14:00:15-03:00"
  }
}

CASHOUT_REFUNDED

Fired when a previously completed Cash-Out is returned asynchronously by the payee's bank via SPI.

{
  "eventType": "CASHOUT_REFUNDED",
  "eventAt": "2026-03-11T09:30:20Z",
  "data": {
    "transactionId": "dd30446e-6cc5-4664-bf3f-6b7f5e55a1a9",
    "internalCode": "IVKPRMOCDY",
    "externalReference": "withdraw_xyz789",
    "endToEndId": "D00416968202603101827cemeFscF6AG",
    "originalEndToEndId": "E00416968202603101827cemeFscF6AG",
    "status": "REFUNDED",
    "amount": 500.00,
    "payee": {
      "name": "Maria Silva",
      "document": "12345678909",
      "destination": {
        "type": "PIX",
        "pixKeyType": "CPF",
        "pixKey": "12345678909"
      },
      "bankData": {
        "ispb": "00000000",
        "bank": "Banco do Brasil S.A.",
        "branch": "0001",
        "account": "123456"
      }
    },
    "requestedAt": "2026-03-10T14:00:00-03:00",
    "paidAt": "2026-03-10T14:02:30-03:00",
    "refundedAt": "2026-03-11T09:30:15-03:00"
  }
}

Event Reference

EventTrigger
CASHIN_PAIDPIX received and confirmed by BACEN/SPI
CASHIN_REFUNDEDA paid Cash-In was fully refunded
CASHOUT_COMPLETEDCash-Out settled successfully
CASHOUT_FAILEDCash-Out rejected at origin or destination
CASHOUT_REFUNDEDA completed Cash-Out was returned by the payee's bank
Previous page
Next page