Webhooks

Webhook Signature Verification

To ensure webhook requests are sent by our API and not forged by third parties, we sign each request using SHA-256.

How it works

Each webhook request includes a header:

X-Signature: <signature>

This signature is generated by signing the raw request payload with the secret you provided during webhook registration.

How to verify

Retrieve the raw payload from the request exactly as received — do not parse or modify it before validation.
Use your webhook secret to compute a SHA-256 HMAC of the raw payload.
Compare the computed HMAC with the value from the X-Signature-SHA256 header.
If they match, the request is authentic.

🚧
Always use the raw payload for signature validation. Parsing or re-encoding the body before computing the signature can lead to mismatches.

Events

PayInCompleted
PayOutCompleted
PayOutRefunded
PayInRefunded

Webhook Event Examples

🔹 PayInCompleted : Payment confirmed successfully.

{
  "data": {
    "account_id": 2,
    "amount": 3,
    "created_at": "2025-08-27T16:59:36.9111Z",
    "end_to_end_id": "E18236120202508271700s00a9b2c354",
    "expiration": 300,
    "id": "8217f189-39dc-4902-a562-243e59cdfd8d",
    "payer": {
      "account_bank": "NU PAGAMENTOS - IP",
      "account_ispb": "18236120",
      "document_number": "04870348306",
      "name": "BRUNO EDUARDO ARAÚJO SOUZA"
    },
    "qr_code_string": "00020101021226870014br.gov.bcb.pix2565pix.delbank.com.br/v2/12573115/cob/TX2025082713598Jqnpeb9TIgbLGsR5204000053039865802BR5907DELBANK6009SAO PAULO62070503***6304C540",
    "refunds": null,
    "status": "paid",
    "txid": "TX2025082713598Jqnpeb9TIgbLGsR"
  },
  "event": "PayInCompleted"
}

🔹 PayOutCompleted : Outgoing payment completed successfully.

{
  "data": {
    "account_id": 2,
    "amount": 1,
    "created_at": "2025-08-27T17:06:24.190536Z",
    "end_to_end_id": "E12573115202508271706Z8hFFYdvcwb",
    "error": null,
    "id": "24147420-095d-4583-8da0-8558776ed8ed",
    "payer": {
      "account_bank": "nel3",
      "account_number": "31216",
      "document_number": "59614054000190",
      "name": "Nel3 New GTW"
    },
    "recipient": {
      "account_bank": "NU PAGAMENTOS - IP",
      "account_ispb": "18236120",
      "document_number": "04870348306",
      "name": "Bruno Eduardo Araújo Souza",
      "pix_key": "04870348306"
    },
    "reference_code": "33043d54-02ab-4069-808b-10b7d1fe17af",
    "refunds": null,
    "status": "done"
  },
  "event": "PayOutCompleted"

🔹PayOutRefunded : Return of an outgoing payment (the recipient or the bank returned the funds).

{
  "data": {
    "amount": 1,
    "created_at": "2025-08-27T17:08:35.279990789Z",
    "end_to_end_id": "D18236120202508271708s00737bbb7d",
    "id": "cf04ea0e-e22e-4ffc-befb-7f2c338ce2ee",
    "original_end_to_end_id": "E12573115202508271706Z8hFFYdvcwb",
    "reference_code": "33043d54-02ab-4069-808b-10b7d1fe17af"
  },
  "event": "PayOutRefunded"
}

🔹PayInRefunded : Return of funds to the payer's account.

This event will be sent when there is support for the return of a receipt (Pay In) initiated via API and will be used every time a PIX receipt is returned to the payer.

{
  "data": {
    "id": "6e543181-4f25-48b4-9eec-03cd22d62cad",
    "txid": "7eff145ff45c418dbe4c46ec5eb8084",
    "amount": 1,
    "end_to_end_id": "E00000000202512192133284b76675fe",
    "original_end_to_end_id": "E18236120202508271700s00a9b2c353",
    "created_at": "2025-08-27T17:08:35.279990789Z"
  },
  "event": "PayInRefunded"
}