Webhooks Introduction
Webhooks allow you to stay updated with Growave data or trigger actions after specific events occur in a shop. They are a more efficient alternative to continuously polling for changes in a shop's data on Growave.
Growave can notify your service when a key business event occurs, such as a customer balance update. These notifications are event-based and delivered to your service via HTTPS.
Webhook topic
Webhooks are organized into topics. Your service subscribes to one topic per shop to receive webhooks each time that type of event is triggered for that shop.
The topic defines the kind of event messages that the service receives. For example, your service can subscribe to the v1/customer/balanceUpdated topic to be notified about customer balance updates.
Webhook subscription
A webhook subscription declares the service's intention to receive webhooks for a topic. A subscription includes the topic and the subscription address, which is the destination where Growave sends webhooks.
For example, if your service needs to know about a customer balance updates, then you can subscribe to the v1/customer/balanceUpdated topic.
Whenever a customer balance updated, an event message is delivered to the address the service set up as the destination when it subscribed.
You can subscribe to a single topic with multiple addresses.
Behavior
Delivery order
Webhooks are sent sequentially within a single topic. However, if a delivery fails and enters retry, subsequent webhooks continue without waiting.
Webhook delivery order is not guaranteed across different topics. For example, a v1/customer/balanceUpdated webhook might arrive before the v1/review/created webhook that triggered the balance change.
Design your service to handle out-of-order events when processing webhooks from multiple topics.
Responses and retries
A 200-series status response is considered successful. If your webhook didn't respond with a 200-series status code, then the delivery failed.
In case of failure, the delivery is retried up to 19 times over a 48-hour period, with increasing intervals between attempts.
If all 19 attempts fail to receive a 200-series response, the subscription to that webhook topic is deleted. You'll need to resubscribe once your service is ready to receive webhook messages again.
Timeout
Growave waits five seconds for a response to each webhook request.
Webhook headers
Each webhook message includes several headers that contain additional info. Here is an example of headers:
X-Growave-Topic: `v1/customer/balanceUpdated`
X-Growave-Hmac-Sha256: `7xVk10OebIRm+dTK2aSu3n6TDY8G+tvovDMggK393/Y=`,
X-Growave-Webhook-Id: `4d121ff2-KDYFHR1-OIDE-bd8d-FHRY267/4695d01c-9384dhe-KDFHE-h3784`,
X-Shopify-Shop-Domain: `{shop}.myshopify.com`
| Field | Use |
|---|---|
X-Growave-Hmac-Sha256 If you're using a PHP, then the header is HTTP_X_GROWAVE_HMAC_SHA256. | Use it to verify webhooks that are sent using HTTPS by Growave |
X-Growave-Webhook-Id | Identify unique webhooks. The webhook ID remains unchanged when Growave retries to resend it. |