Webhooks

Subscribe a server endpoint to lifecycle events emitted by Cimplify. Webhook administration is a server-side surface; all calls require a secret API key (`sk_…`) on `X-API-Key`.

POST /api/v1/webhooks

Register a new endpoint. The response includes a secret; persist it immediately, it is shown only once and is required for signature verification.

Body

Field	Type	Description
`url`	string	HTTPS endpoint URL. Required.
`events`	string[]	Event types to subscribe to. Required.
`description`	string	Optional human-readable label.

Request

cURL

curl -X POST https://api.cimplify.io/api/v1/webhooks \
  -H "X-API-Key: sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/cimplify",
    "events": ["order.created", "order.completed", "payment.completed"]
  }'

Response

{
  "success": true,
  "data": {
    "id": "whk_01H…",
    "url": "https://your-server.com/webhooks/cimplify",
    "events": ["order.created", "order.completed", "payment.completed"],
    "secret": "whsec_xyz789…",
    "status": "active",
    "created_at": "2026-05-07T10:30:00Z"
  }
}

GET /api/v1/webhooks

List all webhooks configured for the calling business.

cURL

curl https://api.cimplify.io/api/v1/webhooks \
  -H "X-API-Key: sk_test_your_secret_key"

DELETE /api/v1/webhooks/{webhook_id}

Remove a webhook subscription. Idempotent.

cURL

curl -X DELETE https://api.cimplify.io/api/v1/webhooks/whk_01H… \
  -H "X-API-Key: sk_test_your_secret_key"

Event types

Event	Description
`order.created`	New order placed via checkout.
`order.updated`	Order status or line items changed.
`order.completed`	Order fulfilled.
`order.cancelled`	Order cancelled.
`payment.completed`	Payment settled.
`payment.failed`	Payment provider returned a failure.
`payment.refunded`	Refund processed.
`booking.created`	Service booking added to an order.
`booking.rescheduled`	Booking moved to a new time.
`booking.cancelled`	Booking cancelled.
`subscription.renewed`	Subscription renewal succeeded.
`subscription.cancelled`	Subscription cancelled.
`inventory.low_stock`	Stock dropped below the configured threshold.

Payload format

Webhooks are POST requests with a JSON body. The type matches the subscription event name; data contains a snapshot of the affected resource.

{
  "id": "evt_01H…",
  "type": "order.created",
  "created_at": "2026-05-07T16:42:18Z",
  "data": {
    "id": "ord_01H…",
    "order_number": "ORD-1284",
    "status": "pending",
    "total_price": "13.06",
    "currency": "GHS"
  }
}

Signature verification

Every webhook includes an X-Cimplify-Signature header. It is the hex-encoded HMAC-SHA256 of the raw request body using the secret returned at registration. Verify in constant time.

import crypto from 'crypto'

export function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex')
  const sig = Buffer.from(signature)
  const exp = Buffer.from(expected)
  return sig.length === exp.length && crypto.timingSafeEqual(sig, exp)
}

Retries

Cimplify retries non-2xx responses with exponential backoff (1m, 5m, 15m, 1h, 6h, 24h) for up to 24 hours. Make your handler idempotent; the same evt_… id may arrive more than once.

Orders Source of order.* events.
Scheduling Source of booking.* events.

Webhooks

On this page