Webhook Retries

If your webhook endpoint doesn’t respond with a 2xx status code, Kyren Pay will automatically retry the delivery.

Retry Schedule

For order and dispute events described in this guide, Kyren Pay makes up to 7 delivery attempts in total: the initial attempt plus 6 retries.

Attempt	Delay After Failure
1st retry	1 minute
2nd retry	5 minutes
3rd retry	15 minutes
4th retry	1 hour
5th retry	6 hours
6th retry	24 hours

Each delay is measured from the preceding failed attempt; actual dispatch may occur later. After 7 failed delivery attempts, the webhook is marked as failed and automatic retries stop.

What Counts as a Failure

A webhook delivery is considered failed if:

Your endpoint returns a non-2xx HTTP status code (e.g., 400, 500)
Your endpoint doesn’t complete its response within 10 seconds
The connection to your server fails (DNS error, connection refused, timeout)

A 2xx response (e.g., 200, 201, 204) is considered a successful delivery regardless of the response body.

Handling Retries

Since webhooks may be retried, your endpoint should be idempotent — processing the same event multiple times should produce the same result.

Use Event IDs for Deduplication

Every webhook event has a unique id field. Store processed event IDs durably, with a unique constraint, and commit the business change and processed marker in the same transaction:

app.post('/webhooks/kyren', async (req, res) => {
  // ... verify signature ...

  const event = JSON.parse(req.body.toString());

  try {
    await database.transaction(async tx => {
      // Atomic insert with a unique event ID; duplicates return false.
      if (!await tx.processedEvents.insertIfAbsent(event.id)) return;
      await processEvent(tx, event);
    });
    res.status(200).send('OK');
  } catch (error) {
    res.status(500).send('Retry later');
  }
});

The database methods above illustrate the transaction contract; adapt them to your storage system. Also protect the business operation with a stable identifier, such as order_id for payment fulfillment or refund_id for a refund. For dispute updates, do not deduplicate only by case ID because one case can have multiple updates.

Return 200 Quickly

For long processing, validate the signature and durably persist the event in an inbox or queue before returning 200. A worker can then process it with its own retries. If persistence fails, return a non-2xx response so Kyren can retry:

app.post('/webhooks/kyren', async (req, res) => {
  // ... verify signature ...

  const event = JSON.parse(req.body.toString());

  try {
    // Resolves only after durable storage; event.id has a unique constraint.
    await webhookInbox.insertIfAbsent(event.id, event);
    res.status(200).send('OK');
  } catch (error) {
    res.status(503).send('Retry later');
  }
});

Monitoring Webhook Deliveries

When troubleshooting delivery, compare Kyren Webhook events with your own server logs. Record:

Your configured Webhook URL
The event type and order number
The timestamp when your server received the request
The response code or error your server returned

If you need Kyren to check delivery attempts, contact support with those details.

Troubleshooting

Problem	Solution
Not receiving webhooks	Check your webhook URL is correct and publicly accessible
Signature verification fails	Ensure you’re using the raw request body (not parsed JSON)
Frequent timeouts	Persist to a durable inbox or queue, return `200` within 10 seconds, then process with worker retries
Duplicate events	Implement idempotency using the event `id` field

Start Here

Dashboard Guide

Webhooks

Troubleshooting

Epay Migration

System Integrations

FAQ

References

Retry Schedule

What Counts as a Failure

Handling Retries

Use Event IDs for Deduplication

Return 200 Quickly

Monitoring Webhook Deliveries

Troubleshooting

​Retry Schedule

​What Counts as a Failure

​Handling Retries

​Use Event IDs for Deduplication

​Return 200 Quickly

​Monitoring Webhook Deliveries

​Troubleshooting

Retry Schedule

What Counts as a Failure

Handling Retries

Use Event IDs for Deduplication

Return 200 Quickly

Monitoring Webhook Deliveries

Troubleshooting