Webhooks

Receive real-time HTTP notifications when events occur.

Setup

Create an HTTPS endpoint on your server
Register the URL in your portal under Settings → Webhooks
Select the events you want to receive

Payload

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

Events

Orders

Event	Description
`order.created`	New order placed
`order.accepted`	Order accepted by merchant
`order.ready`	Order ready for pickup
`order.completed`	Order delivered
`order.cancelled`	Order cancelled

Deliveries

Event	Description
`delivery.assigned`	Driver assigned
`delivery.picked_up`	Order picked up
`delivery.completed`	Delivery completed

Payments

Event	Description
`payment.completed`	Payment successful
`payment.failed`	Payment failed
`payment.refunded`	Refund processed

Verifying Signatures

Every webhook includes an X-Kesk-Signature header. Verify it:

const crypto = require('crypto');

function verify(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retries

Failed deliveries are retried with exponential backoff:

Attempt	Delay
1	Immediate
2	5 minutes
3	30 minutes
4	2 hours
5	24 hours

After 5 failures, the webhook is disabled.

Best Practices

Respond with 200 within 5 seconds
Process events asynchronously
Use the event id for idempotency
Always verify signatures

Business API SDKs

Built with