> 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.

# 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 |