Skip to main content

​
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

EventDescription
product.createdA product was created
product.updatedA product was updated
product.deletedA product was deleted
order.createdAn order was created
order.confirmedAn order was confirmed (payment received)
order.completedAn order was fully completed
order.cancelledAn order was cancelled
payment.completedA payment was successfully processed
payment.failedA payment attempt failed
payment.refundedA payment was refunded
fulfillment.createdA fulfillment was created
fulfillment.shippedA fulfillment was shipped
fulfillment.deliveredA fulfillment was delivered
inventory.lowInventory fell below safety stock
inventory.out_of_stockAvailable inventory reached zero
customer.createdA 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:
AttemptDelay
1stImmediate
2nd5 minutes
3rd30 minutes
4th2 hours
5th24 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"