Overview
Webhooks let you receive real-time notifications when events happen in your store — like a successful payment, a refund, or a dispute. Pandabase sends an HTTP POST request to your endpoint with the event data.
You can configure up to 10 webhooks per store, each listening to specific event types.
Events
| Event | When it fires |
|---|
PAYMENT_PENDING | Checkout session created, waiting for payment |
PAYMENT_PROCESSING | Payment is being processed |
PAYMENT_COMPLETED | Payment succeeded, order fulfilled |
PAYMENT_FAILED | Payment failed |
PAYMENT_REFUNDED | Order was refunded |
PAYMENT_DISPUTED | Customer filed a dispute |
PAYMENT_DISPUTE_WON | Dispute resolved in your favor |
PAYMENT_DISPUTE_LOST | Dispute resolved in customer’s favor |
Payload
Every webhook payload includes:
{
"event": "PAYMENT_COMPLETED",
"id": "evt_...",
"timestamp": "2026-03-11T12:00:00.000Z",
"data": {
"order": {
"id": "ord_...",
"orderNumber": 1042,
"status": "COMPLETED",
"amount": 2999,
"currency": "USD",
"customFields": [],
"metadata": {},
"items": [...]
},
"customer": {
"id": "cus_...",
"email": "customer@example.com"
},
"geo": {
"ip": "203.0.113.1",
"country": "US",
"city": "San Francisco",
"region": "California"
}
}
}
Verification
All webhook payloads are signed with HMAC-SHA256 using your webhook’s secret key. Verify the signature before processing:
- Read the
X-Pandabase-Signature and X-Pandabase-Timestamp headers
- Compute
HMAC-SHA256(webhook_secret, timestamp + "." + raw_body)
- Compare your computed signature with the header value using constant-time comparison
The X-Pandabase-Idempotency header contains a unique ID for each delivery — use it to deduplicate events.
Retries
If your endpoint returns a non-2xx status code or doesn’t respond within 10 seconds, Pandabase retries the delivery up to 3 times with exponential backoff.
Secret rotation
You can rotate your webhook secret at any time. After rotation, the old secret is immediately invalidated — make sure to update your verification code before rotating.
Your webhook endpoint must be publicly accessible over HTTPS. Pandabase
validates URLs against private IP ranges to prevent SSRF — localhost and
internal network addresses are rejected.
