Webhooks

Use webhooks to be notified about events that happen in your store.

Stores can send webhooks that notify your application anytime an event happens. This is especially useful for building custom reporting solutions that need to receive data on order or customer activity.

Why Webhooks

Webhooks are an efficient way to sync data from a store in near real time, keeping your app up to date without the overhead of traditional polling. See the example below for subscribing to order.created events.

Use Cases

Common use cases include, but are not limited to:

• Integrating with external marketing platforms
• Collecting data for external reporting applications
• Integrating with external fulfillment services
• Integrating with dispute management services

Setting Up Webhooks

You can register new webhooks through Settings > Webhooks or the Admin API to send event data to your application endpoint. For each webhook, you can subscribe to all events or select specific events to send to your endpoint. See a list of all events and example event data below.

Webhook Events

Webhook Data Structure

Webhook payloads follow the same structure as Admin API data serializers, which makes them predictable. In general, the data in a webhook payload matches the data you would get by retrieving the same resource through the API. You can set up test webhooks and view the webhook logs in the dashboard to help build and verify your receiver.

{
    "object": "<object>",
    "data": "<object data>",
    "event_id": "<unique event id>",
    "event_type": "<event type>",
    "webhook": "<webhook info>",
    "api_version": "2023-02-10"
}

Below is a full example of a webhook payload for a customer.created event to demonstrate.

{
    "api_version": "2023-02-10",
    "data": {
        "accepts_marketing": true,
        "addresses": [],
        "date_joined": "2021-12-17T14:52:53.715787+07:00",
        "email": "[email protected]",
        "first_name": "Tester",
        "id": 32234664,
        "ip": null,
        "is_blocked": false,
        "language": "en",
        "last_name": "Test",
        "orders_count": 0,
        "phone_number": null,
        "subscriptions_count": 0,
        "tags": [],
        "total_spent": null,
        "user_type": "lead"
    },
    "event_id": "f7eb1338-0934-4cda-8128-d6a77761a368",
    "event_type": "customer.created",
    "object": "customer",
    "webhook": {
        "events": [
            "customer.created"
        ],
        "id": 39,
        "store": "storename",
        "target": "https://webhook.site/6a880c2a-48db-4e28-a575-294dfee934234"
    }
}

Webhook API Versions

Webhook object data structure follows the Admin API and Admin API versioning to ensure predictable data structure for existing webhook receiver endpoints with a path for upgrades.

Handling Webhook API Versions

Your app can add handling logic using the api_version key when receiving and processing data to handle multiple webhook data structures while upgrading to a newer webhook api version.

Verifying Webhook Requests

Webhook endpoints are generally open to the internet and therefore it's a best practice to verify the payload data.

Webhook requests include a header X-29Next-Signature, the value is a signature of the webhook payload signed using the webhook signing secret. Your application can use the signature to verify the payload authenticity, see an example below.

import json

webhook_secret = <YOUR WEBHOOK SIGNING SECRET>

def webhook_payload_validator(request):

    request_sig = request.headers.get('X-29Next-Signature', None)
    webhook_data = json.loads(request.body)

    expected_sig = hmac.new(
        webhook_secret.encode(),
        json.dumps(webhook_data).encode(), hashlib.sha256
    ).hexdigest()

    return True if expected_sig == request_sig else False

As shown above, we can verify the data by generating the same signature with the webhook secret.