> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wepayout.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Real-time notifications for Automatic Pix events

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                            |

<Note>
  All authorization status changes trigger a webhook — there are no silenced intermediate statuses.
</Note>

**Payload:**

```json theme={null}
{
  "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      |

<Note>
  Statuses `Pending` (1), `Sent` (2), and `Canceled Requested` (7) do **not** trigger a webhook.
</Note>

**Payload:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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>
```

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