Skip to Content
DocumentationWebhooks

Webhooks

Webhooks allow your application to receive real-time notifications when events occur in the Kesk platform. Instead of polling for updates, webhooks push data to your server as events happen.

Setting Up Webhooks

1. Create a Webhook Endpoint

Set up an HTTPS endpoint on your server to receive webhook events:

// Express.js example
app.post('/webhooks/kesk', (req, res) => {
  const signature = req.headers['x-kesk-signature'];
  const payload = req.body;
 
  // Verify the webhook signature
  if (verifySignature(payload, signature)) {
    // Process the event
    handleEvent(payload);
    res.status(200).send('OK');
  } else {
    res.status(401).send('Invalid signature');
  }
});

2. Register Your Webhook

Register your endpoint in the developer dashboard or via API:

curl -X POST https://api.kesk.app/v1/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/webhooks/kesk",
    "events": ["order.created", "order.updated", "delivery.completed"]
  }'

Event Types

Order Events

EventDescription
order.createdA new order has been placed
order.updatedOrder status has changed
order.cancelledOrder has been cancelled
order.completedOrder has been delivered

Delivery Events

EventDescription
delivery.assignedDriver assigned to delivery
delivery.picked_upOrder picked up from merchant
delivery.in_transitDelivery in progress
delivery.completedDelivery completed

Payment Events

EventDescription
payment.successfulPayment processed successfully
payment.failedPayment failed
payment.refundedRefund processed

Webhook Payload

All webhook events follow this structure:

{
  "id": "evt_1234567890",
  "type": "order.created",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "order_id": "ord_abc123",
    "status": "pending",
    "total": 25.99,
    "currency": "EUR"
  }
}

Verifying Signatures

All webhook requests include a signature in the X-Kesk-Signature header. Verify this signature to ensure the request came from Kesk:

const crypto = require('crypto');
 
function verifySignature(payload, signature) {
  const secret = process.env.WEBHOOK_SECRET;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
 
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Retry Policy

If your endpoint returns a non-2xx status code, we’ll retry the webhook:

  • Attempt 1: Immediately
  • Attempt 2: After 5 minutes
  • Attempt 3: After 30 minutes
  • Attempt 4: After 2 hours
  • Attempt 5: After 24 hours

After 5 failed attempts, the webhook will be marked as failed and we’ll notify you via email.

Best Practices

  1. Return quickly: Respond with 200 within 5 seconds
  2. Process asynchronously: Queue events for background processing
  3. Handle duplicates: Implement idempotency using event IDs
  4. Verify signatures: Always validate webhook authenticity
  5. Use HTTPS: Webhook endpoints must use TLS encryption
OverviewOverview