--- title: "Webhooks" slug: "webhooks" updated: 2026-07-03T19:08:42Z published: 2026-07-03T19:08:42Z canonical: "help.skio.com/webhooks" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.skio.com/llms.txt > Use this file to discover all available pages before exploring further. # Webhooks ## Before you start - You'll need access to the **API & Integrations** section of your **Skio Dashboard**. - You'll need an endpoint (a URL you control) that can accept incoming POST requests. Skio doesn't host or provide this endpoint for you. ## What are webhooks? Webhooks let Skio automatically send subscription event data to an external system in real time, so you can trigger custom logic (like updating a CRM or logging events in your own database) without polling the Skio API. ## How do I set up a webhook? You can add a webhook URL and choose which subscription events get sent to it from the API Keys page. ### Step 1: Navigate to API Keys In the left-hand menu of your **Skio Dashboard**, go to **API & Integrations** > **API Keys**, then select the **Webhooks** tab. ### Step 2: Add your webhook URL 1. Enter the URL you'd like Skio to send webhook events to. 2. Click **Add webhook**. Once added, your webhook appears in the table along with a **Token**. Use this token to verify that incoming requests actually came from Skio (see **Verifying webhook authenticity** below). ![API Keys page in the Skio Dashboard showing the Webhooks tab, a field to add a webhook URL, and the Event Types section](https://cdn.us.document360.io/a953bba6-c70d-43ce-bc77-d7f32a8fc514/Images/Documentation/base64-converted-image-1783105588774.png) The Webhooks tab under **API & Integrations** > **API Keys**. ### Step 3: Choose which event types to send Under **Event Types**, search for and select the events you want this webhook to receive. ## Verifying webhook authenticity Every webhook Skio sends includes a `skioWebhookToken` field. Compare this value against the token shown for that webhook on the API Keys page to confirm the request actually came from Skio and not a spoofed source. > [!WARNING] > Always check the `skioWebhookToken` on every webhook you receive. Skipping this check means your endpoint could act on requests that didn't actually come from Skio. ## Webhook payload structure Every webhook sends a payload with the following top-level structure: ```plaintext {  "domain": string; // The domain of the shop.  "subscriptionId": string; // The Skio subscription ID that this event affects.  "eventType": string; // The type of event in this webhook (see below for a full list of event types).  "eventData": json; // A JSON blob containing details about the event (see below for a full specification).  "skioWebhookToken": string; // The webhook token from above. } ``` ## Event types and payload schema The `eventType` field tells you what happened, and the shape of `eventData` depends on which event fired. The full JSON schema for every event type is below. **Full JSON Schema** ```plaintext {    "$schema": "http://json-schema.org/draft-07/schema#",    "definitions": {        "AuditEventType": {            "enum": [                "Discount code applied",                "Subscription activated",                "Subscription cancelled",                "Subscription interval/date update",                "orderPlaced",                "productsUpdated"            ],            "type": "string"        },        "SellingPlanInterval": {            "description": "Represents valid selling plan interval.",            "enum": [                "DAY",                "MONTH",                "WEEK",                "YEAR"            ],            "type": "string"        },        "UserType": {            "enum": [                "DashboardUser",                "Skio",                "StorefrontUser"            ],            "type": "string"        }    },    "properties": {        "domain": {            "type": "string"        },        "eventData": {            "anyOf": [                {                    "properties": {                        "shopifyOrderId": {                            "type": "string"                        },                        "shopifyOrderName": {                            "type": "string"                        },                        "subscriptionId": {                            "type": "string"                        },                        "timestamp": {                            "type": "string"                        },                        "userCognitoUsername": {                            "type": [                                "null",                                "string"                            ]                        },                        "userEmail": {                            "type": [                                "null",                                "string"                            ]                        },                        "userType": {                            "$ref": "#/definitions/UserType"                        }                    },                    "type": "object"                },                {                    "properties": {                        "subscriptionId": {                            "type": "string"                        },                        "timestamp": {                            "type": "string"                        },                        "userCognitoUsername": {                            "type": [                                "null",                                "string"                            ]                        },                        "userEmail": {                            "type": [                                "null",                                "string"                            ]                        },                        "userType": {                            "$ref": "#/definitions/UserType"                        }                    },                    "type": "object"                },                {                    "properties": {                        "subscriptionId": {                            "type": "string"                        },                        "timestamp": {                            "type": "string"                        },                        "userCognitoUsername": {                            "type": [                                "null",                                "string"                            ]                        },                        "userEmail": {                            "type": [                                "null",                                "string"                            ]                        },                        "userType": {                            "$ref": "#/definitions/UserType"                        }                    },                    "type": "object"                },                {                    "properties": {                        "newProducts": {                            "items": {                                "properties": {                                    "price": {                                        "type": "number"                                    },                                    "productTitle": {                                        "type": "string"                                    },                                    "productVariantId": {                                        "type": "string"                                    },                                    "productVariantTitle": {                                        "type": "string"                                    },                                    "quantity": {                                        "type": "number"                                    }                                },                                "type": "object"                            },                            "type": "array"                        },                        "oldProducts": {                            "items": {                                "properties": {                                    "price": {                                        "type": "number"                                    },                                    "productTitle": {                                        "type": "string"                                    },                                    "productVariantId": {                                        "type": "string"                                    },                                    "productVariantTitle": {                                        "type": "string"                                    },                                    "quantity": {                                        "type": "number"                                    }                                },                                "type": "object"                            },                            "type": "array"                        },                        "subscriptionId": {                            "type": "string"                        },                        "timestamp": {                            "type": "string"                        },                        "userCognitoUsername": {                            "type": [                                "null",                                "string"                            ]                        },                        "userEmail": {                            "type": [                                "null",                                "string"                            ]                        },                        "userType": {                            "$ref": "#/definitions/UserType"                        }                    },                    "type": "object"                },                {                    "properties": {                        "newIntervalAndDate": {                            "properties": {                                "billingDate": {                                    "type": "string"                                },                                "interval": {                                    "$ref": "#/definitions/SellingPlanInterval"                                },                                "intervalCount": {                                    "type": "number"                                }                            },                            "type": "object"                        },                        "oldIntervalAndDate": {                            "properties": {                                "billingDate": {                                    "type": "string"                                },                                "interval": {                                    "$ref": "#/definitions/SellingPlanInterval"                                },                                "intervalCount": {                                    "type": "number"                                }                            },                            "type": "object"                        },                        "skipped": {                            "type": "boolean"                        },                        "subscriptionId": {                            "type": "string"                        },                        "timestamp": {                            "type": "string"                        },                        "userEmail": {                            "type": [                                "null",                                "string"                            ]                        },                        "userType": {                            "$ref": "#/definitions/UserType"                        }                    },                    "type": "object"                },                {                    "properties": {                        "amount": {                            "type": "number"                        },                        "codePlatformId": {                            "type": "string"                        },                        "method": {                            "enum": [                                "FIXED_VALUE",                                "PERCENTAGE"                            ],                            "type": "string"                        },                        "redeemCode": {                            "type": "string"                        },                        "subscriptionId": {                            "type": "string"                        },                        "timestamp": {                            "type": "string"                        },                        "type": {                            "anyOf": [                                {                                    "enum": [                                        "CANCEL_DISCOUNT",                                        "DISCOUNT_CODE",                                        "FREE_SHIPPING",                                        "GROUP_SUBSCRIPTION",                                        "MANUAL_DISCOUNT",                                        "PREPAID_DISCOUNT",                                        "VOLUME_DISCOUNT"                                    ],                                    "type": "string"                                },                                {                                    "type": "null"                                }                            ]                        },                        "userCognitoUsername": {                            "type": [                                "null",                                "string"                            ]                        },                        "userEmail": {                            "type": [                                "null",                                "string"                            ]                        },                        "userType": {                            "$ref": "#/definitions/UserType"                        }                    },                    "type": "object"                }            ]        },        "eventType": {            "$ref": "#/definitions/AuditEventType"        },        "subscriptionId": {            "type": "string"        }    },    "type": "object" } ``` --- ### FAQ #### Can I limit a webhook to specific events? Yes. Use the **Event Types** section on the Webhooks tab to search for and select only the events you want that webhook to receive. #### How do I know a webhook actually came from Skio? Check that the `skioWebhookToken` value in the payload matches the token shown for that webhook on the API Keys page. If it doesn't match, discard the request.