Webhook Overview

Webhooks allow Kyren Pay to send real-time notifications to your server when events happen in your account — such as a successful payment or a completed payout.

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 processes the event and returns a 200 response

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
Return a 2xx response within 30 seconds

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 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": {}
  }
}

Best Practices

Verify Signatures

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

Return 200 Quickly

Return a 200 response as soon as you receive the webhook. Process the event asynchronously if it takes more than a few seconds.

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 production, consider pushing webhook events to a message queue (e.g., RabbitMQ, SQS) for reliable processing.

Next Steps

Events

See all event types

Signatures

Verify webhook signatures

Retries

Understand retry behavior

Start Here

Dashboard Guide

Webhooks

Troubleshooting

Epay Migration

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