Webhooks

Receive real-time event notifications via HTTP callbacks

Webhooks

Webhooks notify your application when events occur in your store — such as order confirmations, payment completions, or low inventory alerts.

Setting Up

Create a webhook via the Admin API:

curl -X POST https://api.headlesscommerce.io/v1/admin/webhooks \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks",
    "events": ["order.confirmed", "payment.completed"]
  }'

The response includes a secret for verifying webhook signatures.

Event Types

Event	Description
product.created	A product was created
product.updated	A product was updated
product.deleted	A product was deleted
order.created	An order was created
order.confirmed	An order was confirmed (payment received)
order.completed	An order was fully completed
order.cancelled	An order was cancelled
payment.completed	A payment was successfully processed
payment.failed	A payment attempt failed
payment.refunded	A payment was refunded
fulfillment.created	A fulfillment was created
fulfillment.shipped	A fulfillment was shipped
fulfillment.delivered	A fulfillment was delivered
inventory.low	Inventory fell below safety stock
inventory.out_of_stock	Available inventory reached zero
customer.created	A customer was created

Payload Format

{
  "id": "evt_abc123",
  "type": "order.confirmed",
  "created_at": "2025-01-15T10:30:00Z",
  "data": {
    "id": "order_001",
    "number": 1001,
    "status": "confirmed",
    "total": { "amount": 78000, "currency": "KRW" }
  },
  "store_id": "store_001"
}

Verifying Signatures

Each webhook delivery includes an X-Webhook-Signature header (HMAC-SHA256). Verify it to ensure the payload is authentic:

import crypto from 'node: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));
}

Retry Policy

Failed deliveries are retried with exponential backoff:

Attempt	Delay
1st	Immediate
2nd	5 minutes
3rd	30 minutes
4th	2 hours
5th	24 hours

After 5 consecutive failures, the webhook is deactivated and a dashboard notification is sent.

Testing

Send a test event to verify your endpoint:

curl -X POST https://api.headlesscommerce.io/v1/admin/webhooks/{id}/test \
  -H "Authorization: Bearer sk_test_your_key"