Webhooks

Subscribe to real-time event notifications. Requires a secret key (sk_test_ / sk_live_).

POSThttps://api.cimplify.io/v1/webhooks

Create Webhook

Request Body

Field	Type	Description
`url`	string	HTTPS endpoint URL (required)
`events`	string[]	Event types to subscribe to (required)

Example Request

curl

curl -X POST https://api.cimplify.io/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"]
  }'

Example Response

JSON

{
  "success": true,
  "data": {
    "id": "whk_abc123",
    "url": "https://your-server.com/webhooks/cimplify",
    "events": ["order.created", "order.completed", "payment.completed"],
    "secret": "whsec_xyz789...",
    "status": "active",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Save the secret immediately -- it is only shown once. Use it to verify webhook signatures.

GEThttps://api.cimplify.io/v1/webhooks

List Webhooks

Example Request

curl

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

DELETEhttps://api.cimplify.io/v1/webhooks/{id}

Delete Webhook

Example Request

curl

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

Event Types

Event	Description
`order.created`	New order placed
`order.updated`	Order details changed
`order.completed`	Order fulfilled
`order.cancelled`	Order cancelled
`payment.completed`	Payment successful
`payment.failed`	Payment failed
`payment.refunded`	Refund processed
`inventory.low_stock`	Stock below threshold
`customer.created`	New customer registered

Payload Format

Webhooks are sent as POST requests with a JSON body.

JSON

{
  "id": "evt_abc123",
  "type": "order.created",
  "created_at": "2025-01-15T10:30:00Z",
  "data": {
    "id": "ord_abc123",
    "order_number": "ORD-1234",
    "status": "pending",
    "total_price": "27.22",
    "currency": "USD"
  }
}

Signature Verification

Each webhook includes a X-Cimplify-Signature header. Verify it using HMAC-SHA256 with your webhook secret.

TYPESCRIPT

import crypto from 'crypto'

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