Webhooks notify your application in real-time when events occur in PaymentKit. Use webhooks to trigger business logic, sync data, and keep your systems up to date.

How webhooks work

When events occur (like a payment succeeding or subscription being created), PaymentKit sends an HTTP POST request to your configured endpoint with details about the event.

Setting up webhooks

Dashboard

API

Navigate to Developers > Webhooks
Click Add Endpoint
Enter your endpoint URL (must be HTTPS)
Select the events you want to receive
Copy your signing secret for verification

Webhook payload

Webhooks are delivered as JSON with a Stripe-compatible format:

1 {
2   "id": "evt_prod_a1b2c3d4e5f6g7h8",
3   "object": "event",
4   "type": "invoice.paid",
5   "created": 1704067200,
6   "livemode": true,
7   "data": {
8     "object": {
9       "id": "in_prod_a1b2c3d4e5f6g7h8",
10       "status": "paid",
11       "currency": "usd",
12       "total_amount_atom": 290000,
13       "due_amount_atom": 0,
14       "paid_amount_atom": 290000
15     },
16     "previous_attributes": {
17       "status": "open",
18       "due_amount_atom": 290000,
19       "paid_amount_atom": 0
20     }
21   }
22 }

The data.object field contains the full entity state at the time of the event. The example above is simplified; actual payloads include all entity fields. Amount fields use atomic units (e.g., cents for USD) with the _atom suffix. The previous_attributes field contains the previous state for update events, showing fields that changed.

Webhook headers

Each webhook request includes headers for verification and debugging:

Header	Description
`Content-Type`	`application/json`
`X-Webhook-Signature`	HMAC signature for verification
`X-Webhook-Event-Id`	Unique event identifier
`X-Webhook-Event-Type`	Event type (e.g., `invoice.paid`)
`X-Webhook-Delivery-Id`	Unique delivery attempt identifier

Verifying signatures

Always verify webhook signatures to ensure requests are from PaymentKit. The signature is an HMAC-SHA256 hash of the raw request body using your endpoint’s signing secret.

Node.js

Python

1 const crypto = require('crypto');
2 
3 function verifyWebhook(payload, signature, secret) {
4   // Signature format is "sha256=<hex>"
5   const receivedHash = signature.replace('sha256=', '');
6 
7   const expected = crypto
8     .createHmac('sha256', secret)
9     .update(payload, 'utf8')
10     .digest('hex');
11 
12   // Use timing-safe comparison
13   return crypto.timingSafeEquals(
14     Buffer.from(expected),
15     Buffer.from(receivedHash)
16   );
17 }
18 
19 // In your webhook handler
20 app.post('/webhooks', (req, res) => {
21   const signature = req.headers['x-webhook-signature'];
22   const rawBody = req.rawBody; // Ensure you capture raw body
23 
24   if (!verifyWebhook(rawBody, signature, WEBHOOK_SECRET)) {
25     return res.status(401).send('Invalid signature');
26   }
27 
28   const event = JSON.parse(rawBody);
29   // Process event...
30   res.status(200).send('OK');
31 });

Always use the raw request body for signature verification, not a parsed/serialized version. JSON serialization can change formatting and break verification.

Event types

Payment events

Event	Description
`payment.succeeded`	Payment completed successfully
`payment.failed`	Payment attempt failed
`payment.refunded`	Payment was refunded

Checkout session events

Event	Description
`checkout.session.created`	Checkout session created
`checkout.session.updated`	Checkout session updated
`checkout.session.deleted`	Checkout session deleted
`checkout.session.completed`	Checkout session completed successfully
`checkout.session.expired`	Checkout session expired

Payment intent events

Event	Description
`payment_intent.created`	Payment intent created
`payment_intent.processing`	Payment intent is processing
`payment_intent.requires_action`	Payment intent requires additional action
`payment_intent.amount_capturable_updated`	Capturable amount updated
`payment_intent.succeeded`	Payment intent succeeded
`payment_intent.canceled`	Payment intent was canceled
`payment_intent.payment_failed`	Payment intent payment failed
`payment_intent.partially_funded`	Payment intent was partially funded

Subscription events

Event	Description
`customer.subscription.created`	New subscription created
`customer.subscription.updated`	Subscription details changed
`customer.subscription.paused`	Subscription was paused
`customer.subscription.resumed`	Subscription was resumed
`customer.subscription.cancelled`	Subscription was cancelled
`customer.subscription.trial_will_end`	Trial period ending soon

Invoice events

Event	Description
`invoice.created`	New invoice created
`invoice.finalized`	Invoice finalized and ready for payment
`invoice.paid`	Invoice payment succeeded
`invoice.payment_succeeded`	Invoice payment succeeded
`invoice.payment_failed`	Invoice payment failed
`invoice.payment_action_required`	Invoice payment requires additional action
`invoice.overdue`	Invoice is overdue
`invoice.voided`	Invoice was voided
`invoice.marked_uncollectible`	Invoice marked as uncollectible
`invoice.refunded`	Invoice was refunded
`invoice.upcoming`	Upcoming invoice notification

Customer events

Event	Description
`customer.created`	New customer created
`customer.updated`	Customer details changed
`customer.deleted`	Customer was deleted

Customer discount events

Event	Description
`customer.discount.created`	Customer discount created
`customer.discount.updated`	Customer discount updated
`customer.discount.deleted`	Customer discount deleted

Coupon events

Event	Description
`coupon.created`	Coupon created
`coupon.updated`	Coupon updated
`coupon.deleted`	Coupon deleted

Price events

Event	Description
`price.created`	Price created
`price.updated`	Price updated
`price.deleted`	Price deleted

Product events

Event	Description
`product.created`	Product created
`product.updated`	Product updated
`product.deleted`	Product deleted

Refund events

Event	Description
`refund.created`	Refund created
`refund.updated`	Refund updated
`refund.failed`	Refund failed

Retry behavior

If your endpoint returns a server error (5xx status), times out, or is unreachable, PaymentKit automatically retries delivery:

Client errors (4xx status codes) are treated as permanent failures and will not be retried. Ensure your endpoint returns a 2xx status for successful receipt.

Retry	Delay
1	1 minute
2	5 minutes
3	30 minutes
4	2 hours
5	24 hours

After 5 failed attempts, the delivery is marked as permanently failed. You can manually retry from the dashboard.

Respond to webhooks quickly (within 30 seconds) with a 2xx status. Process event data asynchronously to avoid timeouts.

Best practices

Respond quickly

Return a 2xx response immediately, then process the event asynchronously.

Handle duplicates

Use the event ID to deduplicate. Webhooks may be retried on failure, potentially delivering the same event multiple times.

Verify signatures

Always verify webhook signatures in production to prevent spoofing.

Use HTTPS

Webhook endpoints must use HTTPS. PaymentKit rejects HTTP URLs.

Testing webhooks

You can use tools like ngrok to expose your local development server for webhook testing. This allows you to receive real webhook events during development.

Monitoring deliveries

Track webhook delivery status in the dashboard under Events:

delivered - Successfully received (2xx response)
pending - Scheduled for initial delivery
delivering - Currently being delivered
failed - Delivery failed (will retry if attempts remain, or permanent failure if retries exhausted)

View delivery details including attempt count, response status, error messages, and retry timing.