Skip to main content
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. Instead of polling the PIK API repeatedly, you set up a webhook endpoint and PIK calls it automatically when events occur.

​
How webhooks work

When an event occurs in PIK, PIK sends an HTTP POST request to your registered webhook URL. The request body is a JSON object describing the event. Your endpoint must respond with a 200 status code within 10 seconds to acknowledge receipt. If PIK does not receive a 200 response it will retry.

​
Setting up a webhook

Register your webhook URL in the PIK Dashboard under Settings > Webhooks > Add endpoint. Enter your endpoint URL and select the event types you want to receive. You can register multiple endpoints and subscribe each to different event types. Alternatively, register a webhook via the API by calling POST /api/v1/webhooks with your endpoint URL and the list of event types. Your webhook endpoint must be publicly accessible over HTTPS. PIK does not send webhooks to HTTP endpoints or private IP addresses.

​
Verifying webhook signatures

Every webhook request PIK sends includes a PIK-Signature header. This is a HMAC-SHA256 signature of the raw request body, signed with your webhook secret. You must verify this signature on every incoming webhook to confirm it genuinely came from PIK and has not been tampered with. To verify: Step 1 — Retrieve your webhook secret from the PIK Dashboard under Settings > Webhooks. Step 2 — Compute HMAC-SHA256 of the raw request body using your webhook secret as the key. Step 3 — Compare the result to the value in the PIK-Signature header. If they match, the webhook is authentic. If they do not match, discard the request. Never process a webhook that fails signature verification.

​
Retries

If your endpoint does not return a 200 response within 10 seconds, PIK marks the delivery as failed and retries using an exponential backoff schedule. Retry schedule:
  • First retry — 5 minutes after initial 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 PIK stops retrying and marks the event as undelivered. You can manually replay undelivered events from the PIK Dashboard under Settings > Webhooks > Event log.

​
Handling duplicate deliveries

Due to retries, your endpoint may occasionally receive the same event more than once. Make your event handling idempotent — use the event_id field in the webhook payload to detect and discard duplicates.

​
Event types

payment.settled — A payment has been received, verified, and credited to the merchant wallet. payment.expired — A payment request expired without receiving funds. payment.underpaid — Funds were received but the amount was less than requested. payment.overpaid — Funds received exceeded the requested amount. fx.conversion.completed — An FX conversion has completed successfully. fx.conversion.failed — An FX conversion failed. account.verification_status_updated — A connected account’s verification status has changed. account.capability_updated — A connected account’s capability has been activated or deactivated. payout.completed — An outbound payout has been processed successfully. payout.failed — An outbound payout failed.