Webhooks 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
All webhook payloads are signed so you can verify they originated from Ordergroove. We support two signing methods:
- HMAC-SHA256 — a hash-based signature included in the request headers
- AES encryption — payload-level encryption for an additional layer of security
See HMAC and AES Authentication for implementation details.
Configuring Webhooks
Webhooks can be configured through the Ordergroove dashboard or programmatically via the API.
- For the full list of available events and the configuration API reference, see the endpoint documentation in this section.
- For a step-by-step setup walkthrough, see Configure Webhooks via API.
Legacy Webhooks
If your integration was built before the current Webhooks API, you may be using the legacy webhook system. See Webhooks Overview (Legacy) for documentation on the older format, and Configure Webhooks via API for migration guidance.