Webhooks

Webhooks let Ciklek push real-time events to your system as they happen — no polling required.

Enterprise plan only.

How It Works

When an event occurs in Ciklek (e.g. an order is picked up), we send an HTTP POST to your configured endpoint with a JSON payload describing the event.

Your endpoint must return 2xx within 10 seconds. If it doesn't, we retry with exponential backoff.

Setting Up a Webhook

1. Go to Portal → Settings → Webhooks
2. Click Add Endpoint
3. Enter your HTTPS endpoint URL
4. Select the events you want to receive
5. Click Save — we'll send a test event immediately

Endpoints must use HTTPS. Plain HTTP is not accepted.

Verifying Signatures

Every webhook includes a Ciklek-Signature header. Verify it to confirm the request is from Ciklek and has not been tampered with.

Ciklek-Signature: t=1710864000,v1=abc123def456...

Verification steps:

1. Split the header on , to get t (timestamp) and v1 (signature)
2. Construct the signed payload: ${timestamp}.${raw_request_body}
3. Compute HMAC-SHA256 of the signed payload using your webhook signing secret
4. Compare to v1 using a constant-time comparison
5. Check that t is within 5 minutes of current time (replay protection)

Node.js example:

import crypto from 'crypto';

function verifySignature(
  payload: string,
  header: string,
  secret: string
): boolean {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const timestamp = parts['t'];
  const signature = parts['v1'];
  if (!timestamp || !signature) return false;

  // Replay protection
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (age > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex');

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

Your signing secret is shown when you create the endpoint. Store it securely — it cannot be retrieved after the initial display.

Retry Policy

| Attempt | Delay | |---------|-------| | 1st retry | 5 seconds | | 2nd retry | 30 seconds | | 3rd retry | 5 minutes | | 4th retry | 30 minutes | | 5th retry | 2 hours |

After 5 failed attempts, the delivery is marked failed. You can manually replay it from Settings → Webhooks → Deliveries.

Testing Your Endpoint

In Settings → Webhooks, click Send Test Event next to your endpoint. We'll send a test.ping event and show you the delivery log including:

• Request headers
• Request body
• Response status and body
• Latency

Disabling an Endpoint

Click the endpoint → Disable. Events stop being sent. You can re-enable any time. Historical deliveries are preserved.