Webhook Overview

Webhooks allow Kyren Pay to notify your server when a payment or refund succeeds. See Events for supported events and optional dispute notifications.

How Webhooks Work

An event occurs (e.g., a customer completes a payment)
Kyren Pay sends an HTTP POST request to your configured webhook URL
The request includes a signature for verification
Your server verifies the signature, persists the event, and returns 200 within 10 seconds
Your worker processes the persisted event with idempotency and its own retries

Configuring Webhooks

Set up your webhook endpoint in the Merchant Dashboard:

Go to Dashboard > Developer > Webhook Settings
Enter your Webhook URL (e.g., https://yoursite.com/webhooks/kyren)
Copy your Webhook Secret — you’ll need this to verify signatures

Your webhook URL must:

Use HTTPS (required for production)
Be publicly accessible
Complete a 2xx response within 10 seconds, after durable persistence succeeds

Webhook Payload

Every webhook request includes these headers:

Header	Description
`Content-Type`	`application/json`
`X-Kyren-Signature`	HMAC-SHA256 signature for verification
`X-Kyren-Timestamp`	Unix timestamp in milliseconds when the webhook was sent

The request body is a JSON object:

{
  "id": "evt_abc123",
  "type": "order.paid",
  "created_at": 1736932500000,
  "data": {
    "order_id": "order_def456",
    "product_id": "prod_abc123",
    "customer_email": "customer@example.com",
    "amount": "9.99",
    "currency": "USD",
    "net_amount": "9.29",
    "paid_at": 1736932500000,
    "metadata": null
  }
}

Best Practices

Verify Signatures

Always verify the X-Kyren-Signature header to ensure the webhook is authentic. See Webhook Signatures.

Return 200 Quickly

Verify the signature and durably store the event before returning 200. Return non-2xx if persistence fails, so Kyren can retry.

Handle Duplicates

Use the event id to deduplicate. Your endpoint may receive the same event more than once due to retries.

Use a Queue

For asynchronous processing, persist to a durable inbox or queue and acknowledge only after storage succeeds. Workers need their own retries after Kyren receives 2xx.

Next Steps

Events

See all event types

Signatures

Verify webhook signatures

Retries

Understand retry behavior

Start Here

Dashboard Guide

Webhooks

Troubleshooting

Epay Migration

System Integrations

FAQ

References

How Webhooks Work

Configuring Webhooks

Webhook Payload

Best Practices

Verify Signatures

Return 200 Quickly

Handle Duplicates

Use a Queue

Next Steps

Events

Signatures

Retries

​How Webhooks Work

​Configuring Webhooks

​Webhook Payload

​Best Practices

Verify Signatures

Return 200 Quickly

Handle Duplicates

Use a Queue

​Next Steps

Events

Signatures

Retries

How Webhooks Work

Configuring Webhooks

Webhook Payload

Best Practices

Next Steps