Webhook Forwarding

Webhook Forwarding makes it easy to receive near real time events whenever data is updated, changed, or deleted in a Third Party App. Discover how to access this powerful feature.

The Webhook Forwarding feature is designed to make it easy for ISVs to obtain near real-time events whenever important data changes in a Third Party App or specific user events occur.

Example Scenario

Let's say you want to receive an event every time your end users create a new order in their e-commerce application. For this tutorial, we'll use Adobe Commerce (formerly Magento) as an example. With Webhook Forwarding, you can subscribe to these events – even when the underlying application doesn't support webhooks.

How it Works

Webhook forwarding relies on a critical part of the Alloy Unified API: polling and real-time webhooks. Behind the scenes, Alloy leverages an advanced system of real-time webhook subscriptions and periodic polling to ensure the data we cache is continuously up to date.

When an end user makes their first connection, Alloy Unified API subscribes to all relevant webhooks. We also spin up a 12-hour polling sync to reconcile any dropped events (note: this polling frequency can be adjusted to be even more real-time, talk to your account rep if you'd like to explore this).

Taking a look at our Adobe Commerce (Magento) example, this app does not natively expose webhooks via an API. In other words, unlike other e-commerce apps like Shopify, Alloy Unified API does not have webhooks to subscribe to automatically. To remedy this, Alloy performs regular polling to check for changes in Adobe Commerce (Magento). Using Webhook Forwarding, you can subscribe to these events using APIs.


Setting up Webhook Forwarding

To subscribe to events using Webhook Forwarding, you'll need an address that can receive and process webhooks. This address should be a POST endpoint capable of handling incoming body data. You'll also need to specify the events, or topicto subscribe to.


Pro Tip: If you're just testing, we recommend using ngrok to get set up. You can spin up a simple express app in minutes and mirror it to the internet.

Take a look at the example below:

curl --location 'https://embedded.runalloy.com/2024-03/one/webhooks' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{YOUR_API_KEY}}' \
--header 'Content-Type: application/json' \
--data '{
    "address": "{{YOUR_WEBHOOK_ADDRESS}}",
    "topic": [

Parameters Explained

  • address: The URL of the endpoint that will be receiving the events. We strongly advise using HTTPS.
  • topic: An array of events to subscribe to. A full list can be found here.

There are two types of topics you can subscribe to: System events and Data Changed events. System events let you subscribe to user-driven actions such as whenever a user makes a new connection. Data changed events alert you every time data is modified in a Third Party App such as Salesforce CRM.

Response Data

When receiving a webhook using Webhook Forwarding, you'll get data structured as follows. A non-exhaustive description of the most important values is provided below:

Header Data

  • x-alloy-signature: The RSA signature associated with this request. Intended to avoid request spoofing.
  • x-alloy-topic: The name of the topic associated with this event
  'user-agent': 'axios/1.6.2',
  'content-length': '928',
  accept: 'application/json, text/plain, */*',
  'accept-encoding': 'gzip, compress, deflate, br',
  'content-type': 'application/json',
  'x-alloy-signature': 'f722a226a1d611ee8c900242ac120002...',
  'x-alloy-topic': 'commerce/orders',
  'x-forwarded-for': '02.0020.2699.923',
  'x-forwarded-host': '{{YOUR_WEBHOOK_ADDRESS}}',
  'x-forwarded-proto': 'https'

Body Data

  • updateType : Returns the type of event forwarded. If Data has changed, this will return either created, updated, or deleted
  • connectionId: The connectionId associated with this event
  • userId: The userId associated with this event
  • dataPayload: The JSON data for the event. Note that this is structured in the Unified model and does not come through as raw data.
  • category: The category of the app you subscribed to.
  • name The display name of the app where this event is coming from.
  • eventTimestamp The date stamp when the event occurred.
  "connectionId": "6622a1a8f4d6e00352f34650",
  "userId": "6622a1914268110c7ca94986",
  "updateType": "updated",
  "dataPayload": {
    "id": "3bcc9193-c159-4ae0-be7e-6a2f28c11034",
    "remoteId": "5011228328096",
    "createdAt": "2024-04-19T16:57:18.020Z",
    "lineItems": [
        "lineItemId": "13582898790560",
        "productId": "",
        "variantId": "",
        "price": 1,
        "quantity": 2,
        "sku": "",
        "title": "Chocolate Unftle2"
    "orderId": "753f7304-aee1-419e-941f-8f16bb02d801",
    "remoteCreatedAt": "2024-02-15T10:27:58.000Z",
    "remoteDeleted": false,
    "remoteUpdatedAt": "2024-02-15T10:27:58.000Z",
    "trackingNumbers": [],
    "trackingUrls": [],
    "updatedAt": "2024-05-31T18:37:32.353Z"
  "category": "commerce",
  "app": "Magento",
  "userName": "Embedded User",
  "eventTimestamp": "2024-05-31T18:37:32Z"