End User Webhooks

The end_user_webhooks feature lets end users register their own webhook endpoints. When events occur (orders created, shipments shipped, etc.), Orderly sends signed payloads to their URLs.

Enable it by adding end_user_webhooks to your enabled_features.

Each end user can create up to 5 webhooks.

Creating a Webhook


POST /api/embed/webhooks
Authorization: Bearer est_session-token
Content-Type: application/json
 
{
  "url": "https://customer-app.com/webhooks/orderly",
  "secret": "whsec_at-least-16-characters",
  "description": "Order and shipment updates",
  "events": ["order.created", "shipment.shipped", "shipment.delivered"]
}

The secret is optional but recommended. If provided, it must be at least 16 characters. Orderly uses it to sign payloads with HMAC-SHA256.

Managing Webhooks

List Webhooks


GET /api/embed/webhooks
Authorization: Bearer est_session-token

Update Webhook


PATCH /api/embed/webhooks/:id
Authorization: Bearer est_session-token
Content-Type: application/json
 
{
  "events": ["order.created", "order.updated", "shipment.shipped"],
  "is_active": true
}

Delete Webhook


DELETE /api/embed/webhooks/:id
Authorization: Bearer est_session-token

Event Types


GET /api/embed/webhooks/event-types
Authorization: Bearer est_session-token

Returns the list of supported event types that can be subscribed to.

Testing

Send a test payload to verify the webhook endpoint is reachable:


POST /api/embed/webhooks/:id/test
Authorization: Bearer est_session-token

Response:


{
  "success": true,
  "statusCode": 200
}

The test sends a webhook.test event:


{
  "event": "webhook.test",
  "organizationId": "uuid",
  "endUserId": "uuid",
  "timestamp": "2026-03-21T18:00:00Z",
  "data": {
    "message": "This is a test event"
  }
}

Payload Signature

When a secret is configured, every delivery includes an X-Orderly-Signature header containing a base64-encoded HMAC-SHA256 signature of the payload body.

Verify it on your server:


const crypto = require('crypto');
 
function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('base64');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Delivery Logs

View recent delivery attempts for a webhook:


GET /api/embed/webhooks/:id/deliveries
Authorization: Bearer est_session-token

Returns the last 50 deliveries with status codes, success/failure, and error messages.

Automatic Disabling

Webhooks are automatically disabled after consecutive failures. The disabled_reason field indicates why, and consecutive_failures tracks the failure count.