Webhooks Quickstart

Register For Webhooks

During your onboarding call, you will register to receive webhooks from us. Each event that you subscribe to will trigger a webhook notification each time they occur.

Enter your Webhook URL when creating your project:

or inside the app form:

Webhook Payload

Webhook notifications will come as an HTTPS POST request with the event’s data to your callback URL. The event’s data is included in the body of the request.

The payload will vary across events, but will always take the following form:

{
  "appollo_merchant_id": MERCHANT_APPOLLO_ID,
  "merchant_name":  MERCHANT_NAME,
  "merchant_email": MERCHANT_EMAIL,
  "merchant_shop": MERCHANT_SHOP_DOMAIN,
  "platform": MERCHANT_PLATFORM
  "topic": WEBHOOK_TOPIC,
  "created_at":  CREATION_DT,
  "last_update_at":  UPDATE_DT,
  "url" : WEBHOOK_CALLBACK_URL,
  "data":{
         "id": WEBHOOK_ID
        }
 }

Where the fields have the above meaning/options

Field

Values

appollo_merchant_id

The ID of the merchant that this webhook is for
e.g. "appollo_merchant_id": 1

merchant_name

The name of the merchant that this webhook is for e.g.
"merchant_name": "John Doe"

merchant_email

The email of the merchant that this webhook is for e.g.
"merchant_email": "[email protected]"

merchant_shop

The shop domain of the merchant that this webhook is for e.g.
"merchant_shop": "woolworths.myshopify.com"

platform

The platform the merchant store is build on e.g.
"platform": "SHOPIFY"

topic

The webhook topic. e.g. billing_update

created_at

ISO time When the webhook was first triggered. e.g. "created_at': "2021-06-27T08:48:27-04:00"

last_update_at

ISO time When the webhook was last triggered. e.g. "last_update_at': "2021-06-27T09:48:27-04:00"

url

The callback URL where webhook delivers its data with the topics and other details.

List of Supported Webhooks

app_uninstall Payload Example

{
  "appollo_merchant_id": "123456",
  "merchant_name":  "example",
  "merchant_email": "[email protected]",
  "merchant_shop": "shop.myshop.com",
  "platform": "shopify",
  "topic": "customer_create",
  "created_at":  "2021-06-19T13:36:57Z",
  "last_update_at":  "2021-06-19T13:40:57Z",
  "url": "https://webhook.url/",
  "data":{
      "id": 12345
     }
 }

billing_update Payload Example

{
  "appollo_merchant_id": "123456",
  "merchant_name":  "example",
  "merchant_email": "[email protected]",
  "merchant_shop": "shop.myshop.com",
  "platform": "shopify",
  "topic": "customer_create",
  "created_at":  "2021-06-19T13:36:57Z",
  "last_update_at":  "2021-06-19T13:40:57Z",
  "url": "https://webhook.url/",
  "data":{
      "id": 12345,
      "type": "PLAN_PURCHASE"
     }
 }

N.B. type supports "PLAN_PURCHASE", "PLAN_CANCEL", "PLAN_EXPIRED"

customer_create, customer_update Payload Example

{
        "platform": "shopify",
        "merchant_shop": "myshop.shopify.com",
        "created_at": "2021-06-19T13:37:06.381Z",
        "topic": "customer_create",
        "merchant_email": "[email protected]",
        "appollo_merchant_id": "1324548454",
        "merchant_name": "Example Person",
        "last_update_at": "2021-06-19T13:40:57Z",
        "url": "https://webhook.url/",
        "data": {
            "id": 29,
            "first_name": "Jon",
            "last_name": "Doe",
            "created_at": "2021-06-19T13:36:57Z",
            "phone": "+123456789012",
            "email": "[email protected]",
            "address": {
                "address_1": "Addr 1",
                "address_2": "Addr 2",
                "first_name": "Ronald",
                "last_name": "Swimmer"
            }
        }
    }
{
        "platform": "shopify",
        "merchant_shop": "myshop.shopify.com",
        "created_at": "2021-06-19T13:37:06.381Z",
        "topic": "customer_update",
        "merchant_email": "[email protected]",
        "appollo_merchant_id": "1324548454",
        "merchant_name": "Example Person",
        "last_update_at": "2021-06-19T13:40:57Z",
        "url": "https://webhook.url/",
        "data": {
            "id": 29,
            "first_name": "Updated Name",
            "last_name": "Updated Doe",
            "created_at": "2021-06-19T13:36:57Z",
            "phone": "+1234589012",
            "email": "[email protected]",
            "address": {
                "address_1": "Updated Addr 1",
                "address_2": "Addr 2 ",
                "first_name": "Cooler Ronald",
                "last_name": "Swimmer"
            }
        }
    }

product_create, product_update Payload Examples

{
  "appollo_merchant_id": "123456",
  "merchant_name":  "example",
  "merchant_email": "[email protected]",
  "merchant_shop": "shop.myshop.com",
  "platform": "shopify",
  "topic": "product_create",
  "created_at":  "2021-06-19T13:36:57Z",
  "last_update_at":  "2021-06-19T13:40:57Z",
  "url": "https://webhook.url/",
  "data": {
    "id": 29,
        "created_at": "2021-06-19T13:36:57Z",
        "description": "A really good product",
        "title": "Product Title",
        "tags": ["Some", "Product", "Tag"],
        "media": [
            {
                "type": "image",
                "src": "http://www.example.com/image.png"
            }
        ],
        "options": [
            {
                "name": "Color",
                "choices": ["Red", "Green", "Blue"]
            }
        ],
        "variant": [
            {
                "id": "1124454",
                "price": "1.00",
                "sku": "SKUGDPRD"
            }
        ],
        "product_type": "Digital"
      }
}
{
  "appollo_merchant_id": "123456",
  "merchant_name":  "example",
  "merchant_email": "[email protected]",
  "merchant_shop": "shop.myshop.com",
  "platform": "shopify",
  "topic": "product_update",
  "created_at":  "2021-06-19T13:36:57Z",
  "last_update_at":  "2021-06-19T13:40:57Z",
  "url": "https://webhook.url/",
  "data": {
    "id": 29,
        "created_at": "2021-06-19T13:36:57Z",
        "description": "A really good product that just got updated",
        "title": "Updated Product Title",
        "tags": ["Some", "Product", "Tag"],
        "media": [
            {
                "type": "image",
                "src": "http://www.example.com/image.jpg"
            },
            {
                "type": "video",
                "src": "http://www.example.com/video.mp4"
            },
          
        ],
        "options": [
            {
                "name": "Color",
                "choices": ["Red", "Green", "Blue"]
            },
            {
                "name": "Size",
                "choices": ["X", "S", "M"]
            }
        ],
        "variant": [
            {
                "id": "1124454",
                "price": "100.00",
                "sku": "SKUGDPRD"
            }
        ],
        "product_type": "Physical"
      }
}

N.B. The media.type will be one of "Image" , "Video".

customer_delete, product_delete, collection_delete Payload Examples

{
  "appollo_merchant_id": "123456",
  "merchant_name":  "example",
  "merchant_email": "[email protected]",
  "merchant_shop": "shop.myshop.com",
  "platform": "shopify",
  "topic": "customer_delete",
  "created_at":  "2021-06-19T13:36:57Z",
  "last_update_at":  "2021-06-19T13:40:57Z",
  "url": "https://webhook.url/",
  "data" : {
    "id":"114545",
   }
}
{
  "appollo_merchant_id": "123456",
  "merchant_name":  "example",
  "merchant_email": "[email protected]",
  "merchant_shop": "shop.myshop.com",
  "platform": "square",
  "topic": "product_delete",
  "created_at":  "2021-06-19T13:36:57Z",
  "last_update_at":  "2021-06-19T13:40:57Z",
  "url": "https://webhook.url/",
  "data" : {
     "id": "DDASKJELFXXAWDS",
   }
}
{
  "appollo_merchant_id": "123456",
  "merchant_name":  "example",
  "merchant_email": "[email protected]",
  "merchant_shop": "shop.myshop.com",
  "platform": "big_commerce",
  "topic": "collection_delete",
  "created_at":  "2021-06-19T13:36:57Z",
  "last_update_at":  "2021-06-19T13:40:57Z",
  "url": "https://webhook.url/",
  "data" : {
     "id": "11",
   }
}

N.B. if the topic is one of "customer_delete" , "product_delete", "collection_delete". Only the id will be returned.

collection_create, collection_update Payload Examples

{
  "appollo_merchant_id": "123456",
  "merchant_name":  "example",
  "merchant_email": "[email protected]",
  "merchant_shop": "shop.myshop.com",
  "platform": "shopify",
  "topic": "collection_create",
  "created_at":  "2021-06-19T13:36:57Z",
  "last_update_at":  "2021-06-19T13:40:57Z",
  "url": "https://webhook.url/",
  "data": {
        "id": "12454",
        "name": "Summers Collection",
        "image": "http://www.example.com/image.png"
    }
}
{
  "appollo_merchant_id": "123456",
  "merchant_name":  "example",
  "merchant_email": "[email protected]com",
  "merchant_shop": "shop.myshop.com",
  "platform": "shopify",
  "topic": "collection_update",
  "created_at":  "2021-06-19T13:36:57Z",
  "last_update_at":  "2021-06-19T13:40:57Z",
  "url": "https://webhook.url/",
  "data": {
        "id": "12454",
        "name": "Winters Collection",
        "image": "http://www.example.com/winter-image.png"
    }
}

order_create, order_update Payload Examples

{
        "appollo_merchant_id": "1324548454",
        "platform": "shopify",
        "merchant_shop": "myshop.shopify.com",
        "created_at": "2021-06-19T13:37:06.381Z",
        "last_update_at":  "2021-06-19T13:40:57Z",
        "topic": "order_create",
        "merchant_email": "[email protected]",
        "merchant_name": "Example Person",
        "url": "https://webhook.url/",
        "data": {
            "id": "1234",
            "created_at": "2021-06-19T13:36:57Z",
            "currency": "USD",
            "billing_address": {
                "address_1": "Addr 1",
                "address_2": "Addrs 2",
                "first_name": "First Name",
                "last_name": "Last Name"
            },
            "line_items": [
                {
                    "product_id": "12343",
                    "quantity": "1",
                    "price": "1.00",
                    "sku": "SKUGDPRD",
                    "name": "Good Product",
                    "variant_id": "1123ASDS"
                }
            ],
            "shipping_address": {
                "address_1": "Addr 1",
                "address_2": "Addrs 2",
                "first_name": "First Name",
                "last_name": "Last Name"
            },
            "fulfillment_status": "NOT_FULFILLED"
        }
}
{
        "appollo_merchant_id": "1324548454",
        "platform": "shopify",
        "merchant_shop": "myshop.shopify.com",
        "created_at": "2021-06-19T13:37:06.381Z",
        "last_update_at":  "2021-06-19T13:40:57Z",
        "topic": "order_create",
        "merchant_email": "[email protected]",
        "merchant_name": "Example Person",
        "url": "https://webhook.url/",
        "data": {
            "id": "1234",
            "created_at": "2021-06-19T13:36:57Z",
            "currency": "GBP",
            "billing_address": {
                "address_1": "Updated Addr 1",
                "address_2": "Addrs 2",
                "first_name": "First Name",
                "last_name": "Updated Last Name"
            },
            "line_items": [
                {
                    "product_id": "12343",
                    "quantity": "10",
                    "price": "100.00",
                    "sku": "SKUGDPRD",
                    "name": "Really good Product",
                    "variant_id": "1123"
                }
            ],
            "shipping_address": {
                "address_1": "Addr 1",
                "address_2": "Addrs 2",
                "first_name": "First Name",
                "last_name": "Last Name"
            },
            "fulfillment_status": "PENDING"
        }
}

N.B. fulfillment_status will be one of "FULFILLED" , "NOT_FULFILLED", "PENDING", "CANCELLED".

order_status_update Payload Example

{
        "appollo_merchant_id": "1324548454",
        "platform": "shopify",
        "merchant_shop": "myshop.shopify.com",
        "created_at": "2021-06-19T13:37:06.381Z",
        "last_update_at":  "2021-06-19T13:40:57Z",
        "topic": "order_status_update",
        "merchant_email": "[email protected]",
        "merchant_name": "Example Person",
        "url": "https://webhook.url/",
        "data": {
           "id": "1234",
           "fulfillment_status": "FULFILLED"
        }
}

N.B. for order_status_update it will always return the order id and the updated fulfillment_status of that order

Webhook Retry Mechanism

Your callback URL must respond with a 200 status to notify us that you received the POST. If not we will repeatedly reattempt the webhook with an exponential backoff delay for up to 48 hours.

🚧

One more thing!

You should check the webhook payload id to avoid reprocessing the same event twice.


Did this page help you?