Genstore webhook

Webhooks are automated notifications sent to a specified URL when specified events occur. In Genstore, developers can subscribe to specific webhook topics to receive real-time notifications about store activities such as order creations or product updates. Unlike REST APIs that require active request initiation by apps, webhooks allow apps to passively receive notifications pushed by the platform, greatly enhancing data processing efficiency.

Use cases

For apps that need real-time synchronization of store orders, considering the limited call frequency of REST APIs, it is advisable to subscribe to the "order creation" (orders/create) webhook topic upon app installation. This approach ensures that whenever a new order is generated, your app immediately receives a notification, effectively reducing reliance on REST APIs and significantly enhancing the timeliness of data synchronization.

WARNING

• Webhook notifications do not guarantee the order of events.
• After 8 consecutive failures, the system will cease attempts to send notifications, which may result in data loss.

Key concepts

Webhook topics

Webhook topics define the types of events that can be subscribed to. Developers can subscribe one or more topics based on their needs. When an event corresponding to a subscribed topic occurs, the app receives an immediate notification.

Webhook topics are categorized by business domain.

Webhook subscriptions

A webhook subscription involves specifying which events an app wants to receive notifications for. When setting up a subscription, the following information is required:

• Topic name to subscribe to
• HTTPS endpoint to receive notifications

For further details, see Webhook Subscription

Webhook headers

Each webhook notification includes standard headers and a payload. The headers contain critical information such as the topic name, signature, and shop domain, ensuring secure data transmission.

X-Genstore-Topic: `orders/create`
X-Genstore-Hmac-Sha256: `4iiJMXWsseFppeH5Jo4by6OsHH3cmAMeJAwLMeiZKwP=`
X-Genstore-Shop-Domain: `{shop}.genmystore.com`
X-Genstore-API-Version: `202412`
X-Genstore-Webhook-Id: `bf5l8lbcd088-4b87-6a5f -bdd9-b58557e8 `
X-Genstore-Triggered-At: `2024-12-30T23:59:59.888889999Z`
X-Genstore-Event-Id: `8c9f0dx091b5-b7ad-88c8-7008-98887460 `

Parameters:

• X-Genstore-Topic: Webhook topic name
• X-Genstore-Hmac-SHA256: Signature verification
• X-Genstore-Shop-Domain: Shop domain
• X-Genstore-API-Version: API version
• X-Genstore-Webhook-Id: Unique ID of the app's Webhook subscription
• X-Genstore-Triggered-At: Time when the event message was triggered
• X-Genstore-Event-Id: Unique ID of the event message

REST API polling and webhook event notifications

REST API polling

Apps need to frequently query the REST API to check for new orders. This method, although straightforward, is inefficient and can waste resources.

Webhook event notifications

Apps subscribe to Webhooks, and when relevant events (e.g., a new order) occur, Genstore proactively sends notifications.