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

# Webhooks

> How to receive real-time event notifications from PIK, verify webhook signatures, and handle retries.

Webhooks allow PIK to push real-time notifications to your server when something happens — a payment is settled, a conversion completes, or an account's verification status changes.

### How webhooks work

When an event occurs, PIK sends an HTTP POST to your registered webhook URL with a JSON payload describing the event. Your endpoint must respond with 200 within 10 seconds. If PIK does not receive a 200 response it will retry.

### Setting up a webhook

Register your webhook URL in PIK Dashboard under Settings > Webhooks > Add endpoint. Select the event types you want to receive.

Via API — Call POST /api/v1/webhooks with your endpoint URL and event type list.

Your endpoint must be publicly accessible over HTTPS.

### Verifying signatures

Every webhook request includes a PIK-Signature header — a HMAC-SHA256 signature of the raw request body, signed with your webhook secret.

To verify:

Step 1 — Retrieve your webhook secret from PIK Dashboard under Settings > Webhooks. Step 2 — Compute HMAC-SHA256 of the raw request body using the secret as the key. Step 3 — Compare the result to the PIK-Signature header value. Discard requests that do not match.

Never process a webhook that fails signature verification.

### Retries

If your endpoint does not return 200 within 10 seconds, PIK retries with exponential backoff:

* First retry — 5 minutes after failure.
* Second retry — 30 minutes after first retry.
* Third retry — 2 hours after second retry.
* Fourth retry — 8 hours after third retry.
* Fifth retry — 24 hours after fourth retry.

After 5 failed attempts the event is marked undelivered. Replay events manually from PIK Dashboard under Settings > Webhooks > Event log.

### Handling duplicates

Use the event\_id field in the webhook payload to detect and discard duplicates.

### Event types

payment.settled — Payment received, verified, and credited to wallet. payment.expired — Payment request expired without receiving funds. payment.underpaid — Funds received were less than requested. payment.overpaid — Funds received exceeded requested amount. fx.conversion.completed — FX conversion completed successfully. fx.conversion.failed — FX conversion failed. account.verification\_status\_updated — Connected account verification status changed. account.capability\_updated — Capability activated or deactivated. payout.completed — Outbound payout processed successfully. payout.failed — Outbound payout failed.