> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.ordergroove.com/reference/webhooks-overview/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.ordergroove.com/_mcp/server. # Webhooks API Overview 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](/data/webhook-troubleshooting#watching-webhook-route-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](/data/hmac-auth) 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](/data/configure-webhooks). --- ## Legacy Webhooks If your integration was built before the current Webhooks API, you may be using the legacy webhook system. See [Webhooks Overview (Legacy)](/data/webhooks-overview) for documentation on the older format, and [Configure Webhooks via API](/data/configure-webhooks) for migration guidance. --- ## Related Guides | Guide | Description | | ----------------------------------------------------------------------------- | --------------------------------------------- | | [HMAC and AES Authentication](/data/hmac-auth) | Verify webhook payloads are from Ordergroove | | [Webhooks Overview (Legacy)](/data/webhooks-overview) | Legacy webhook format and event list | | [Configure Webhooks via API](/data/configure-webhooks) | Register and manage webhook endpoints | | [Expiring or Termed Subscriptions Using Webhooks](/data/termed-subscriptions) | Handle subscription expiry events | | [Using Webhooks for 1-Click Actions](/lifecycle/order/webhooks-1-click) | Trigger upsell and action flows from webhooks | > APIs, SDKs, and guides for building subscription commerce with Ordergroove.