Webhooks

Automatic Pix sends webhook notifications to your configured endpoint whenever a relevant status change occurs. There are three distinct webhook types: authorization updates, schedule updates, and payin (transaction) updates.

Authorization Webhook

Sent whenever an authorization transitions to a new status. Your endpoint receives a POST request with the following payload. Trigger statuses:

Status ID	Status Name	Description
1	Confirmed	Authorization approved by the payer
2	Pending	Authorization created and awaiting payer confirmation
3	Canceled	Authorization was canceled
4	Rejected	Authorization was rejected

All authorization status changes trigger a webhook — there are no silenced intermediate statuses.

Payload:

{
  "entity": "authorization",
  "id": 3081,
  "contract_id": "10000:1234:2:aabbccdd112233aabbccdd112233aabb",
  "status": {
    "id": 1,
    "name": "Confirmed"
  },
  "updated_at": "2026-01-15T10:00:00.000-03:00"
}

Field reference:

Field	Type	Description
`entity`	string	Always `"authorization"`
`id`	integer	Internal authorization ID
`contract_id`	string	Authorization contract identifier
`status.id`	integer	Numeric status code
`status.name`	string	Human-readable status name
`updated_at`	string	ISO 8601 timestamp of the status change

Schedule Webhook

Sent whenever a schedule transitions to a notifiable status. Your endpoint receives a POST request with the following payload. Trigger statuses:

Status ID	Status Name	Description
3	Scheduled	Payment successfully scheduled
4	On Retry	Payment failed and is being retried
5	Canceled	Payment was canceled
6	Paid	Payment completed successfully

Statuses Pending (1), Sent (2), and Canceled Requested (7) do not trigger a webhook.

Payload:

{
  "entity": "schedule",
  "id": 1042,
  "contract_id": "10000:1234:2:aabbccdd112233aabbccdd112233aabb",
  "status": {
    "id": 6,
    "name": "Paid"
  },
  "metadata": {
    "amount": 150.00,
    "tx_id": "WP01AABBCC112233DDEEFF4455667788"
  },
  "updated_at": "2026-01-15T10:30:00.000-03:00"
}

Field reference:

Field	Type	Description
`entity`	string	Always `"schedule"`
`id`	integer	Internal schedule ID
`contract_id`	string	Authorization contract identifier
`status.id`	integer	Numeric status code
`status.name`	string	Human-readable status name
`metadata.tx_id`	string	Internal transaction identifier generated by WEpayments
`metadata.amount`	float	Amount charged — only present when `status.id` is `6` (Paid)
`sub_status`	object	Optional. Additional context for the transition (e.g., cancellation reason)
`updated_at`	string	ISO 8601 timestamp of the status change

Payin Webhook

Sent when an Automatic Pix payin reaches a final or relevant status. All intermediate statuses are silenced — the webhook fires only on the events below. Trigger statuses: 4 — Credited → Payment successfully received Canceled → Payment was canceled Rejected → Payment was rejected Payload:

{
  "id": 200001,
  "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "invoice": "10000:1234:2:aabbccdd112233aabbccdd112233aabb-20260115",
  "end_to_end": "E99999999202601151330xXxXxXxXxXx",
  "status": {
    "id": 4,
    "name": "Credited"
  },
  "metadata": {
    "paid_amount": 150.00,
    "payer": {
      "document": "12345678900"
    },
    "contract_id": "10000:1234:2:aabbccdd112233aabbccdd112233aabb",
    "bank_payer": {
      "name": "341 - ITAÚ UNIBANCO S.A.",
      "bank_ispb": "60701190",
      "bank_account": null,
      "bank_branch": null,
      "bank_account_type": null
    }
  },
  "updated_at": "2026-01-15T13:30:00.000000Z"
}

Field reference:

Field	Type	Description
`id`	integer	Internal payin ID
`hash`	string	SHA-256 fingerprint of this payin, used for signature verification
`invoice`	string	Composed of the `contract_id` and the payment date (`contract_id-YYYYMMDD`)
`end_to_end`	string	PIX end-to-end identifier assigned by the Brazilian payment system (SPI) — can be used for reconciliation and dispute resolution
`status.id`	integer	Numeric status code
`status.name`	string	Human-readable status name
`metadata.paid_amount`	float	Amount actually received
`metadata.payer.document`	string	Payer’s CPF/CNPJ
`metadata.contract_id`	string	Authorization contract identifier
`metadata.bank_payer`	object	Payer’s bank details — only present when your contract has `send_bank_payer_into_webhook` enabled
`updated_at`	string	ISO 8601 timestamp of when the status was recorded

Signature Verification

All webhook requests include an x-webhook-wp-signature header for authenticity verification. Authorization and Schedule webhooks — signature is computed as:

SHA-256(merchantID | contractID | apiKey)

Payin webhook — signature is computed as:

SHA-256(id | hash | amount | apiKey)

The header value is prefixed with Bearer :

x-webhook-wp-signature: Bearer <hex-encoded-sha256>

Always validate the signature before processing any webhook payload to ensure the request originates from WEpayments.

Introduction

Account

Banks

Payin

Payout

Markup

Authorization Webhook

Schedule Webhook

Payin Webhook

Signature Verification

​Authorization Webhook

​Schedule Webhook

​Payin Webhook

​Signature Verification

Authorization Webhook

Schedule Webhook

Payin Webhook

Signature Verification