> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.ordergroove.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.ordergroove.com/_mcp/server. # Configure Webhooks via API Ordergroove can send webhook events to an endpoint or endpoints of your choosing. In order to set up which webhook events you want triggered to which endpoint, you'll need to: 1. Configure each target endpoint that you want events to be sent to 2. Configure which events you want sent to the target endpoint > **Legacy Method** > > We recommend setting up webhooks directly in the Ordergroove merchant dashboard under Developers > [Webhooks](https://rc3.ordergroove.com/webhooks/). If you need to set up webhooks via API, please contact your Customer Success Manager or technical resource at Ordergroove. --- ## Authentication We recommend you set up webhooks directly in the [Ordergroove merchant dashboard](https://rc3.ordergroove.com/), under *Developers > Webhooks*. If you need to set webhooks up via API, please contact your Customer Success Manager or technical resource at Ordergroove to discuss authentication options. --- ## Creating a Target Endpoint > **Platform — Shopify** > > For merchants on Shopify, please make sure you create a new Target Endpoint and do not update or use an existing endpoint that is configured for Shopify Event Notifications. **Destination** * Staging: `https://staging.webhooks.ordergroove.com/webhook_targets/` * Production: `https://webhooks.ordergroove.com/webhook_targets/` **`Request Body`** ```json title="Request Body" { "merchant": "abc12345", "target_url": "https://www.mywebhooktargeturl.com/receive/", "enabled": true } ``` **`Response`** ```json title="Response" { "id": "5f15ef298dc15df9bc6eda35", "merchant": "abc12345", "target_url": "https://www.mywebhooktargeturl.com/receive/", "enabled": true, "created": 1595273001, "updated": 1597260663 } ``` For more information on all targets that exist, how to update targets, or how to get target metrics, check out our [Webhook Targets REST endpoint documentation](/reference/webhooks-api/webhook-targets/list) for additional details. --- ## Defining Events to Send to a Webhook Target Once you've created a Webhook Target, you can define which events you want to be sent to that endpoint. The ID returned in the response of the Target Creation step is what will be used in this API request for the `target_id` in the path parameter. **Destination** * Staging: `https://staging.webhooks.ordergroove.com/webhook_targets/{target_id}/filters` * Production: `https://webhooks.ordergroove.com/webhook_targets/{target_id}/filters` *To define multiple events, use a pipe separator as shown:* **`Example Request Body`** ```json title="Example Request Body" {"pattern": "subscription.*|order.*"} ``` Each object type documented here has its own reference page, listing its events, what triggers them, and the fields their payloads carry: | Object | Filter pattern | Reference | | ------------ | ---------------- | ------------------------------------------------ | | Subscriber | `subscriber.*` | [Subscriber events](/data/subscriber-events) | | Subscription | `subscription.*` | [Subscription events](/data/subscription-events) | | Order | `order.*` | [Order events](/data/order-events) | | Order item | `item.*` | [Item events](/data/item-events) | --- ## Receiving Event Notifications ### Payload Verification Requests will be signed using the HMAC-SHA256 algorithm with a symmetric key we store and share with you at the time of configuration. A webhook event will be delivered with the request header `OrderGroove-Signature` which will contain: * a timestamp of transmission * a hex-encoded representation of a signature generated with HMAC-SHA256 **`Example Signature`** ```text title="Example Signature" OrderGroove-Signature: ts=1592570791,sig=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd ``` It is strongly encouraged to verify the authenticity of events. A Python example below shows how one might go about using the JSON values provided in the header to verify the signature. ```python ts = "1592570791" payload = u'' sig_key = "shared symmetric key" sig_input = "{ts}.{payload}".format(ts=ts, payload=payload) hash_obj = hmac.new(key=bytes(sig_key, 'ascii'), msg=bytes(sig_input, 'utf-8'), digestmod=hashlib.sha256) generated_sig = hash_obj.hexdigest() # "5257a869e7...." return generated_signature == header_signature ``` As shown above, via the `sig_input` variable, the signature is driven by: * the timestamp provided in the request header * a period (`.`) * the payload of the webhook event **Signing Key Retrieval** Signing keys are considered sensitive data and should only be retrieved when absolutely necessary. * Staging: `https://staging.webhooks.ordergroove.com/webhook_targets//signing_key` * Production: `https://webhooks.ordergroove.com/webhook_targets//signing_key` **`Response`** ```json title="Response" { "signing_key": "5f15ef298dc15df9bc6eda35" } ``` **Signing Key Rotation** Like passwords, keys should be rotated on a regular basis. While we do not dictate this cadence (yet), you may rotate keys for a particular target on demand. Once this process is activated, events will be delivered with one signature for each active key. Patch Request Destination: * Staging: `https://staging.webhooks.ordergroove.com/webhook_targets//signing_key/rotate` * Production: `https://webhooks.ordergroove.com/webhook_targets//signing_key` **`Response`** ```json title="Response" { "signing_key": "5f15ef298dc15df9bc6eda35", "expiring_signing_key": "GBBYToAvYGBBYToAvYGBBYToAvY", "signing_key_expiry": 1597260663 } ``` The `signing_key_expiry` field will tell you when the `expiring_signing_key` will be discarded and no longer used. Consecutive requests to this endpoint will generate a new value in the `signing_key`, but the timer for the `signing_key_expiry` will not update. You will have 24 hours from the first time this endpoint is hit to make sure your applications are using the new key, whichever it may be. Any subsequent requests sent to the "Signing Key Retrieval" endpoint will only respond with the new key. **Key Rotation** If the rotation of a signing key occurred, there will be two `sig` fields present, providing one signature for each key. **`Example Signature`** ```text title="Example Signature" sig=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd,sig=da32affa62cdca35257a869e7e56ff536d0ce8e108d8bdcebefa51cad7e77a0e ``` **Retries and Automatic URL Disabling** * **Retries**: If a target does not return a `2xx` HTTP response status, the delivery is retried automatically using exponential backoff. The first retry is delayed about 60 seconds, and the wait grows with each attempt up to a maximum of 10 minutes between attempts. A delivery is attempted up to 60 times over roughly 9 to 10 hours, after which it is marked as a failure. See [Delivery behavior](/reference/webhooks-overview#delivery-behavior) for the full contract, including timeouts and ordering. * **URL Disabling**: After 3 days, if a target does not provide a `2xx` HTTP response status, the URL will automatically be disabled. Any success will reset the disable logic. Re-enabling a disabled URL will also reset the disable logic.