# Webhooks


> Receive and verify transaction status events.

Canonical: https://docs.chiwapay.com/webhooks

Webhooks are sent to the URL registered in the merchant dashboard.

## Events

```txt
payment.created
payment.pending
payment.paid
payment.expired
payment.cancelled
payment.failed
payment.refund_processing
payment.refund_failed
payment.refunded
payment.settled
```

| Event | Description |
| --- | --- |
| `payment.created` | Transaction was created. |
| `payment.pending` | Waiting for payment. |
| `payment.paid` | Payment was received. |
| `payment.expired` | Payment deadline has passed. |
| `payment.cancelled` | Transaction was cancelled. |
| `payment.failed` | Payment failed. |
| `payment.refund_processing` | Refund is being processed. |
| `payment.refund_failed` | Refund failed. |
| `payment.refunded` | Refund succeeded. |
| `payment.settled` | Transaction has entered settlement. |

## Payload

```json
{
  "id": "f2b1d5b0-7b1f-4c5d-9c37-93f0c8f6a001",
  "event": "payment.paid",
  "reference_id": "PAY-LXAMPLE",
  "merchant_reference_id": "ORDER-1024",
  "status": "paid",
  "environment": "live",
  "amount": 150000,
  "fee_amount": 1050,
  "net_amount": 150000,
  "total_amount": 151050,
  "currency": "IDR",
  "payment_method": "qris",
  "provider": "gopay",
  "created_at": "2026-05-19T10:00:00Z",
  "updated_at": "2026-05-19T10:01:00Z"
}
```

## Headers

```http
Content-Type: application/json
User-Agent: ChiwaPay-Webhooks/0.1
X-Chiwa-Event: payment.paid
X-Chiwa-Delivery: 1d4c...
X-Chiwa-Signature: t=1779184860,v1=<hmac_sha256_hex>
```

Verify `X-Chiwa-Signature` before processing the payload.