Webhooks

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

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

{
    "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"
}

Webhook Creation Response Object

Attribute	Type	Description
id	integer`readonly`	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

Webhooks are organized into events. Your app subscribes to one or more events to receive webhooks. Once installed on your recurpay store, your app will receive webhooks each time that type of event is triggered for that store.

For example, your app can subscribe to the subscription_renewed topic to be notified about subscription renewals. The event name identifies the nature of the event that's occurred.Refer to the Webhooks references for the complete list of supported webhook topics.

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.

Verify 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-SHA256 header. If the HMAC digest and header value match, then the webhook was sent from Recurpay.