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

Payin webhooks support the recommended HMAC-SHA256 signature. When your account has a webhook registered for the payin event with a secret, the request includes the x-webhook-wp-type (payin-pix), x-webhook-wp-timestamp and x-webhook-wp-signature headers, where:

x-webhook-wp-signature = hex( HMAC_SHA256( secret, raw_body + x-webhook-wp-timestamp ) )

See Webhook Signature for all headers and verification examples.

Deprecated: Authorization and Schedule webhooks, and Payin webhooks without a registered webhook, are still signed with the deprecated API key signature. See Webhook Signature.

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