Skip to Content
BridgesWebhooks

Bridge Webhooks

Webhooks let your bridge receive real-time events from external platforms — like when an order is created or a shipment is updated.

Declaring Webhooks

Declare supported webhook events in your manifest:

{
  webhooks: [
    {
      event: 'orders/create',
      description: 'Triggered when a new order is placed',
      auth: {
        type: 'hmac',
        header: 'x-shopify-hmac-sha256',
        algorithm: 'sha256',
        secretField: 'webhookSecret',
      },
    },
    {
      event: 'orders/updated',
      description: 'Triggered when an order is modified',
      auth: {
        type: 'hmac',
        header: 'x-shopify-hmac-sha256',
        algorithm: 'sha256',
        secretField: 'webhookSecret',
      },
    },
  ],
}

HMAC Verification

Orderly automatically verifies HMAC signatures when auth.type is 'hmac':

  1. The incoming request header (e.g., x-shopify-hmac-sha256) is extracted
  2. The raw body is signed using the secret from the bridge’s config field (secretField)
  3. The signatures are compared — if they don’t match, the webhook is rejected

Handling Webhooks

Implement the handleWebhook method on your bridge:

async handleWebhook(
  event: string,
  payload: Record<string, unknown>,
  context: BridgeTaskContext
): Promise<BridgeTaskResult> {
  switch (event) {
    case 'orders/create':
      return this.handleOrderCreate(payload, context);
    case 'orders/updated':
      return this.handleOrderUpdate(payload, context);
    default:
      context.logger.warn('Unhandled webhook event', { event });
      return { success: true };
  }
}

Webhook Results

Return a BridgeTaskResult with the processed data:

async handleOrderCreate(payload, context) {
  const order = transformToUnifiedOrder(payload);
 
  return {
    success: true,
    data: {
      action: 'create',
      order,
    },
    metrics: { recordsCreated: 1 },
  };
}

The action field tells Orderly what happened:

  • create — A new record was created
  • update — An existing record was modified
  • delete — A record was removed
  • noop — No action was needed (e.g., duplicate event)

Webhook URL

Each bridge instance gets a unique webhook URL:

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

Configure this URL in the external platform’s webhook settings. The bridge ID is available in the portal under Bridges > [Bridge] > Webhook URL.

TasksOAuth