The list of all webhook topics you can subscribe to. You can use webhook subscriptions to receive notifications about particular events in a subscription..
🔒 Requires read-webhooks or write-webhooks access scope.
You can use webhook subscriptions to receive notifications about particular events in recurpay. After you've subscribed to a webhook topic, your app can execute code immediately after specific events occur in recurpay related to Recurpay stores that have your app installed, instead of having to make API calls periodically to check their status.
For example, you can rely on webhooks to trigger an action in your app when a subscription is cancelled, or when a new subscription is created. By using webhooks, you can make fewer API calls overall, which makes sure that your apps are more efficient and updated quickly. For more information on how webhooks work and how to test them, refer to Webhooks overview.
To learn how to verify webhooks, refer to Verify the webhook.
The webhook's object
{
"id": 9442,
"address": "https://webhook.site/9281c6b3-2b36-43e5-938c-bb119b149d7d",
"topic": "subscription_discount_updated",
"api_version": "2024-07",
"format": "json",
"fields": [],
"metafield_namespaces": [],
"private_metafield_namespaces": [],
"status": true,
"created_at": "2024-07-04 23:08:31",
"updated_at": "2024-07-04 23:08:31"
}
The webhook resource
| Attribute | Type | Description |
|---|---|---|
| id | integerreadonly | An unsigned 64-bit integer that's used as a unique identifier for the webhook subscription. Each id is unique across the Recurpay system. No two webhook subscriptions will have the same id, even if they're from different apps. |
| address | string | Destination URI to which the webhook subscription should send the POST request when an event occurs. |
| topic | enum | Event that triggers the webhook. You can retrieve data in JSON. See list of webhook events. |
| api_version | enum | The Admin API version that Recurpay uses to serialize webhook events. This value is inherited from the app that created the webhook subscription. |
| format | string readonly | Format in which the webhook subscription should send the data. Valid value currently is JSON and defaults to JSON. |
| fields | array readonly | An optional array of top-level resource fields that should be serialized and sent in the POST request. If absent, all fields will be sent. |
| metafield_namespaces | array | Optional array of namespaces for any metafields that should be included with each webhook. |
| private_metafield_namespaces | array | Optional array of namespaces for any private metafields that should be included with each webhook. |
| status | boolean readonly | Status of the webhook subscription, The subscribed webhook will only receive the data if the status is true. |
| created_at | string readonly | The autogenerated date and time (ISO 8601 format) when the webhook subscription was created. The value for this property cannot be changed. |
| updated_at | string readonly | The date and time (ISO 8601 format) when the webhook subscription was last modified. |
Webhook Events
| Topic | Description |
|---|---|
| order_created | Occurs whenever an order is created. Resource: Order Access scopes: read-orders or write-orders, read-customers-write-customers. |
| subscription_created | Occurs whenever a subscription is created. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_edited | Occurs whenever a subscription's line is edited. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_cancelled | Occurs whenever a subscription's line is edited. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_paused | Occurs whenever a subscription is paused. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_skipped | Occurs whenever a subscription's rext order date is skipped. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_activated | Occurs whenever a subscription is resumed. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_expired | Occurs whenever a subscription is auto expired. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_halted | Occurs whenever a subscription is halted. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_renewal_reminder | Occurs whenever a subscription's renewal is reminded. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_address_updated | Occurs whenever a subscription's shipping or billing address is updated. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_payment_updated | Occurs whenever a subscription's payment method is updated. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_discount_updated | Occurs whenever a subscription line items discount is updated. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_delivery_price_updated | Occurs whenever a subscription's delivery price is updated. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_coupon_applied | Occurs whenever a coupon is applied to a subscription. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_coupon_removed | Occurs whenever a coupon is removed from a subscription. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_auto_cancellation_updated | Occurs whenever a subscription's auto cancellation policy is updated. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_line_item_properties_updated | Occurs whenever a subscription line item's attribute is updated. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_renewed | Occurs whenever a subscription is renewed. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_contact_information_email_updated | Occurs whenever a subscriber's details are updated. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_renewal_updated | Occurs whenever a subscription's upcoming renewal date is updated. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_frequency_updated | Occurs whenever a subscription's delivery/billing frequency is updated. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_note_attribute_updated | Occurs whenever a subscription's attribute is updated. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
| subscription_order_note_updated | Occurs whenever a subscription's order note is updated. Resource: Subscription Access scopes: read-subscriptions or write-subscriptions, read-customers-write-customers. |
Verifying the webhook
Before you respond to a webhook, you need to verify that the webhook was sent from Recurpay. You can verify the webhook by calculating a digital signature.
Each webhook includes a base64-encoded X-Recurpay-Hmac-SHA256 field in the payload header, which is generated using the app's client secret along with the data sent in the request.
- Get the raw body of the request
- Extract the signature header value
- Calculate the HMAC of the raw body using the SHA-256 hash function and the secret
- Compare the computed value to the value in the
X-Recurpay-Hmac-SHA256header. If the HMAC digest and header value match, then the webhook was sent from Recurpay.
Webhooks overview
When your app needs information about specific events that have occurred on Recurpay store, it can subscribe to Recurpay webhook topics as a mechanism for receiving near-real-time data about these events.
Recurpay webhooks are useful for keeping your app in sync with Recurpay data or as a trigger to perform an additional action after that event has occurred. They are also a performant alternative to continuously polling for changes to a store's data.
This guide provides a quick primer on when to use APIs versus webhooks, as well as key terminology and behaviors that are specific to Recurpay webhooks.
Key terminology
Webhook topic
Webhooks are organized into topics. Your app subscribes to one or more topics to receive webhooks. Once installed on your recurpay store, your app will receive webhooks each time that type of event is triggered for that shop.
The webhook topic defines the kind of event messages that your app receives. For example, your app can subscribe to the subscription_renewed topic to be notified about subscription renewals. The topic name identifies the nature of the event that's occurred.
Webhooks are divided by topic. Refer to the Webhooks references for the complete list of supported webhook topics.
Headers
Each webhook is made up of headers and a payload. Headers contain metadata about the webhook, like the shop that the app was installed on and where the event occurred.
| Header | What it is |
|---|---|
| X-Recurpay-Webhook-Id | Identifying unique webhooks. |
| X-Recurpay-Topic | The name of the topic. Use the webhooks references to match this to the enum value when configuring webhook subscriptions using the Admin API. |
| X-Recurpay-API-Version | Specifies which version of the Admin API was used to serialize the webhook event payload. |
| X-Recurpay-Shop-Id | Associated store id. |
| X-Recurpay-Shop-Domain | Identifying the associated store. Especially useful when configuring webhook subscriptions using the Admin API. |
| X-Recurpay-Hmac-SHA256 | Verification, when using HTTPS delivery. |