Webhooks API Overview
Receive real-time event notifications from Ordergroove when subscription and order activity occurs
Ordergroove webhooks let you subscribe to events that happen within the platform — subscription creation, order placement, payment updates, cancellations, and more — and receive HTTP POST notifications to a URL of your choosing in real time.
How Webhooks Work
When a subscribed event occurs in Ordergroove, we send an HTTP POST request to the endpoint URL you’ve configured. The request body contains a JSON payload describing the event and the associated data.
Your endpoint should return a 2xx response to acknowledge receipt.
Delivery behavior
Ordergroove delivers webhooks over HTTPS as a POST request with a JSON body. Build your receiver around the four behaviors below — each one changes how you should write the handler.
Retries
If your endpoint doesn’t return a 2xx, Ordergroove retries the delivery automatically using exponential backoff. The first retry follows after about a minute, 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 that it’s marked failed and retries stop.
You can see how often this is happening for a route on the webhook metrics page.
Timeouts
A delivery attempt times out if your endpoint doesn’t respond within 10 seconds.
Acknowledge with a 2xx as soon as you’ve stored the payload, and do the real processing asynchronously. A handler that calls other services before responding will exceed the window under load, even when it’s working correctly.
Duplicate deliveries
The same event can reach you more than once, through a retry or a transient system error. Make your handler idempotent rather than assuming exactly-once delivery — the event id in the payload is stable across retries of the same event, so it works as a deduplication key.
Ordering
Deliveries aren’t guaranteed to arrive in the order the events occurred. Don’t infer sequence from arrival order; use the created timestamp in the payload, and write handlers that tolerate an out-of-order arrival.
Authentication
Ordergroove signs every webhook request so you can confirm it’s genuine. Each webhook route has its own verification key, which you copy from Developers > Webhooks in RC3.
The signature arrives in the Ordergroove-Signature request header:
sig is a hash-based message authentication code (HMAC) that uses SHA-256 and the route’s verification key, encoded as hex. It’s computed over the ts value, a period (.), and the request body. To verify a request, compute the same value with your copy of the key and compare it with sig.
When you regenerate a route’s verification key, the header carries two sig values for 24 hours, one signed with the new key and one with the old, so a request verifies against either key. Check each sig value, not just the first. After 24 hours, only the new key’s signature is sent.
For a worked example and the rotation steps:
- Webhooks Verification checks a signature in Python, with a test request you can send to a local server.
- Webhook Authentication covers regenerating a route’s key in RC3 and the 24-hour transition.
Configuring webhooks
Create and manage webhooks in RC3 under Developers > Webhooks. Setting up a Webhook walks through creating a route, choosing its events, and disabling, re-enabling, or deleting it. The Subscriber, Subscription, Order, and Item events pages describe the events a route can send.
Configuring webhooks through the API is the legacy method, and Ordergroove recommends RC3 instead. If you need the API, contact your Customer Success Manager or technical resource at Ordergroove first. Configure Webhooks via API and the endpoints in this section document it.