Webhooks

Receive incoming webhooks from external platforms (e.g., Shopify, ShipStation) to trigger real-time data syncs. Each bridge has its own webhook URL that accepts events from the connected platform.

Receive Webhook

Accepts incoming webhook payloads from external platforms. The bridge ID in the URL determines which bridge processes the event. Orderly validates the webhook signature (if configured) and queues the event for processing.

Path Parameters

Headers

Webhook verification varies by platform. Common patterns include:

Webhook URL Format

Your bridge webhook URL follows this pattern:

https://api.orderly.dev/api/webhooks/{bridge_id}

Register this URL in the external platform’s webhook settings.

Request Body

The request body contains the raw webhook payload from the external platform. The format depends on the platform and event type.

# Example: Shopify order creation webhook
curl -X POST "https://api.orderly.dev/api/webhooks/550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Hmac-Sha256: abc123..." \
  -d '{
    "id": 123456789,
    "order_number": "#1001",
    "email": "jane@example.com",
    "line_items": [...]
  }'

Response

Returns 200 OK to acknowledge receipt. The webhook is processed asynchronously.

{
  "data": {
    "received": true,
    "event_id": "uuid"
  }
}

Error Responses

Webhook Processing

After receiving a webhook, Orderly:

1. Validates the webhook signature against the bridge’s configured secret
2. Queues the event for asynchronous processing via QStash
3. Executes the appropriate bridge task (e.g., grab-orders for a new order event)
4. Updates the relevant records in Orderly
5. Triggers any matching dispatchers