Webhooks

Webhook endpoints

Webhooks are a mechanism for reacting to specific events that are triggered in the Recharge system.
For example, a checkout completion, a customer activation or subscription cancellation. Webhooks will deliver you the data of the specific event in real-time. This data can be used to custom code logic behind automated subscription management, dashboards creation, discounts applying...

When a webhook is triggered, the payload will be identical to the payload you would receive from another API endpoint.

For example, a webhook on subscription/created will be identical to the payload for retrieving a subscription by ID from the Recharge API.

There are a lot of things that can be done via Webhooks: It can be used to collect all kinds of data from our API and then create a custom Dashboard to show how much and when your customers are buying in real time, or use all this data to do Analytics of some kind in order to create a better customer experience. Webhooks can be used as a “Trigger” on your backend to update subscription products.

If you have some kind of a Subscription where you want to change the Product that the customer gets every month, you can do it by waiting for an order/created webhook on your backend, and when it fires you can make an API call to change the Product of that subscription or the next shipping date, etc.

Retries / Idempotency

Due to webhook retries, it’s possible that your application receives the same webhook more than once. Ensure idempotency of the webhook call by detecting such duplicates within your application.

Respond to a webhook

Your webhook acknowledges that it received data by sending a 200 OK response. Any response outside of the 200 range will let Recharge know that you didn’t receive your webhook. Recharge has implemented a 5 second time-out period. We wait 5 seconds, if our system doesn’t get a response in that period we consider that request as failed. Our system will try 20 times to send the same webhook over the next 2 days, if the request fails every time our system will delete this webhook. At this moment our system is logging those deleted webhooks.

3 additions in V2, marked New

Everything marked New also works when you send X-Recharge-Version: 2021-11.

Endpoints

POST/webhooks
GET/webhooks/{id}
PUT/webhooks/{id}
DELETE/webhooks/{id}
GET/webhooks
POST/webhooks/{id}/test

#The Webhook object

Please note that the store domain header has changed to X-Recharge-External-Platform-Domain

These topics are deprecated, however they will not be removed from this API version: checkout/completed.

Attributes

idinteger
Unique numeric identifier for the webhook.
addressstring
The URI where the webhook should send the POST request when the event occurs.
included_objectsarray
List of objects set to enrich the webhook payload. cf. extending responses
Possible values
addressaddressescharge_activitiescustomereventevent_chargemetafieldspayment_methodssubscriptions
topicstring
The event that will trigger the webhook.
versionstring
The version of the API used to populate the body of the webhook. If not set, this will default to the store's default API version. 2021-11 is V2.
Possible values
2021-012021-11

RelatedExtending webhook responses →

The Webhook object

{
  "webhook": {
    "id": 19451,
    "address": "https://request.in/foo",
    "included_objects": [],
    "topic": "subscription/created",
    "version": "2021-11"
  }
}

#Available webhooks

The list of all available webhooks.

Related guides: Webhook payload examples

Topic	Sent when	Scope required
Address
`address/created`	Fires when an `Address` is created.	`read_customers`
`address/updated`	Fires when an `Address` is updated.	`read_customers`
`address/deleted` New	Fires when an `Address` is deleted.	`read_customers`
`address/payment_method/updated` New	Fires when the `PaymentMethod` associated with an `Address` is changed.	`read_customers`
Async_batch
`async_batch/processed`	Fires when all tasks of an async batch have been processed and the batch is completed.	`read_batches`
`async_batch/started` New	Fires when an async batch starts running its tasks.	`read_batches`
BundleSelection
`bundle_selection/created`	Fires when a `BundleSelection` is created.	`read_subscriptions`
`bundle_selection/deleted`	Fires when a `BundleSelection` is deleted.	`read_subscriptions`
`bundle_selection/updated`	Fires when a `BundleSelection` is updated.	`read_subscriptions`
Charge
`charge/created`	Fires when a `Charge` is created.	`read_orders`
`charge/deleted`	Fires when a `Charge` is deleted.	`read_orders`
`charge/failed`	Fires when a payment attempt for a `Charge` fails.	`read_orders`
`charge/max_retries_reached`	Fires when a failed `Charge` has reached the maximum number of payment retries.	`read_orders`
`charge/paid`	Fires when a `Charge` is processed successfully.	`read_orders`
`charge/refunded`	Fires when a `Charge` is fully or partially refunded.	`read_orders`
`charge/uncaptured`	Fires when the authorized payment of a `Charge` has still not been captured six days after its scheduled date. Only relevant for stores that authorize payments and capture them later.	`read_orders`
`charge/upcoming`	Fires ahead of a queued `Charge`, the number of days in advance set in the store's upcoming charge notification settings.	`read_orders`
`charge/updated`	Fires when a `Charge` is updated.	`read_orders`
Checkout
`checkout/completed`	Fires when a `Checkout` is processed successfully. Only fires for stores that use the Recharge Checkouts API.	`read_orders`
`checkout/created`	Fires when a `Checkout` is created. Only fires for stores that use the Recharge Checkouts API.	`read_orders`
`checkout/processed`	Fires when a `Checkout` is processed successfully, together with `checkout/completed`. Only fires for stores that use the Recharge Checkouts API.	`read_orders`
`checkout/updated`	Fires when a `Checkout` is updated. Only fires for stores that use the Recharge Checkouts API.	`read_orders`
Customer
`customer/activated`	Fires when a `Customer` goes from having no active subscriptions to having at least one.	`read_customers`
`customer/created`	Fires when a `Customer` is created.	`read_customers`
`customer/deactivated`	Fires when a `Customer` no longer has any active subscriptions or one-time purchases.	`read_customers`
`customer/deleted`	Fires when a `Customer` is deleted.	`read_customers`
`customer/payment_method_updated`	Fires when the payment information of a `Customer` is updated.	`read_customers`
`customer/updated`	Fires when a `Customer` is updated.	`read_customers`
Gift Purchase
`gift_purchase/created`	Fires when a gift purchase is created. Only fires for stores that offer gift purchases.	`read_gift_purchases`
`gift_purchase/updated` New	Fires when a gift purchase is updated. Only fires for stores that offer gift purchases.	`read_gift_purchases`
`gift_purchase/redeemed`	Fires when the recipient redeems a gift purchase. Only fires for stores that offer gift purchases.	`read_gift_purchases`
`gift_purchase/unclaimed` New	Fires once when a gift purchase that was sent to its recipient has not been redeemed within the reminder period. Only fires for stores that offer gift purchases.	`read_gift_purchases`
`gift_purchase/sent` New	Fires when the gift notification is sent to the recipient of a gift purchase. Only fires for stores that offer gift purchases.	`read_gift_purchases`
Onetime
`onetime/created`	Fires when a `Onetime` is created.	`read_subscriptions`
`onetime/deleted`	Fires when a `Onetime` is deleted.	`read_subscriptions`
`onetime/updated`	Fires when a `Onetime` is updated.	`read_subscriptions`
Order
`order/cancelled`	Fires when an `Order` is cancelled.	`read_orders`
`order/created`	Fires when an `Order` is created.	`read_orders`
`order/deleted`	Fires when an `Order` is deleted.	`read_orders`
`order/payment_captured`	Fires when the authorized payment for an `Order` is captured. Only relevant for stores that authorize payments and capture them later.	`read_orders`
`order/processed`	Fires when an `Order` has been processed.	`read_orders`
`order/success`	Fires when an `Order` is created with a successful status, or when its payment is captured.	`read_orders`
`order/upcoming`	Fires ahead of a queued prepaid `Order`, the number of days in advance set in the store's upcoming order notification settings. Only prepaid orders trigger this topic.	`read_orders`
`order/updated`	Fires when an `Order` is updated.	`read_orders`
`order/delayed` New	Fires when a queued prepaid `Order` is delayed.	`read_orders`
PaymentMethod
`payment_method/created` New	Fires when a `PaymentMethod` is created.	`read_payment_methods`
`payment_method/deleted` New	Fires when a `PaymentMethod` is deleted.	`read_payment_methods`
`payment_method/expired` New	Fires when the card of a `PaymentMethod` will have expired by the date of an upcoming `Charge`.	`read_payment_methods`
`payment_method/updated` New	Fires when a `PaymentMethod` is updated.	`read_payment_methods`
Plan
`plan/created`	Fires when a `Plan` is created.	`read_plans`
`plan/updated`	Fires when a `Plan` is updated.	`read_plans`
`plan/deleted`	Fires when a `Plan` is deleted.	`read_plans`
Recharge
`recharge/uninstalled`	Fires when Recharge is uninstalled from the store.	`store_info`
Store
`store/updated`	Fires when the `Store` or one of its settings is updated.	`read_store`
Subscription
`subscription/activated`	Fires when a cancelled `Subscription` is activated again.	`read_subscriptions`
`subscription/cancelled`	Fires when a `Subscription` is cancelled.	`read_subscriptions`
`subscription/expired` New	Fires when a `Subscription` expires. It is followed by `subscription/cancelled`.	`read_subscriptions`
`subscription/created`	Fires when a `Subscription` is created.	`read_subscriptions`
`subscription/deleted`	Fires when a `Subscription` is deleted.	`read_subscriptions`
`subscription/skipped`	Fires when a `Subscription` is skipped for a `Charge`.	`read_subscriptions`
`subscription/swapped`	Fires when the product of a `Subscription` is swapped for another product or variant.	`read_subscriptions`
`subscription/unskipped`	Fires when a skipped `Subscription` is unskipped.	`read_subscriptions`
`subscription/updated`	Fires when a `Subscription` is updated.	`read_subscriptions`
`subscription/paused`	Fires when a `Subscription` is paused by moving its next charge date.	`read_subscriptions`
`subscription/removed_from_skipped_charge`	Fires when a `Subscription` is removed from a `Charge` it had been skipped on.	`read_subscriptions`

#Create a webhook

POST/webhooks

Create a webhook. Currently, only the API can be used to create a webhook.

To register a webhook endpoint for a specific object, you will need to have read permissions for that object on your Recharge API token. For example, if you want to register a webhook for subscription/created, you will need the read_subscriptions permissions.

Each API token can register a maximum of 10 webhooks of the same topic.

Related guides: Webhook payload examples

Returns 201. The app that owns the token must hold the scope required by the topic (otherwise 403). Creating a webhook with the same topic, address, version and included objects as an existing one returns 422, and by default an app can have at most 50 webhooks per topic and version on a store.

Body parameters

addressstringRequired
The URI where the webhook should send the POST request when the event occurs.
included_objectsarray
List of objects set to enrich the webhook payload. cf. extending responses
Possible values
addressaddressescharge_activitiescustomereventevent_chargemetafieldspayment_methodssubscriptions
topicstringRequired
The event that will trigger the webhook.
versionstring
The version of the API used to populate the body of the webhook. If not set, this will default to the store's default API version. For V2, send v2 or 2021-11. Both are saved and returned as 2021-11.
Possible values
v22021-012021-11

RelatedExtending webhook responses →

POST/webhooks

curl -X POST 'https://api.rechargeapps.com/webhooks' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
  "address": "https://request.in/foo",
  "topic": "subscription/created",
  "version": "v2"
}'

Response

{
  "webhook": {
    "id": 6,
    "address": "https://request.in/foo",
    "topic": "subscription/created",
    "included_objects": [],
    "version": "2021-11"
  }
}

#Retrieve a webhook

GET/webhooks/{id}

Retrieve a webhook using the Recharge webhook id.

GET/webhooks/{id}

curl 'https://api.rechargeapps.com/webhooks/19451' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

Response

{
  "webhook": {
    "id": 6,
    "address": "https://request.in/foo",
    "topic": "subscription/created",
    "included_objects": [],
    "version": "2021-11"
  }
}

#Update a webhook

PUT/webhooks/{id}

Modifies an existing Webhook to match the specified parameters.

Only non-empty values are applied, so included_objects cannot be cleared by sending an empty array.

Body parameters

addressstring
The URI where the webhook should send the POST request when the event occurs.
included_objectsarray
List of objects set to enrich the webhook payload. cf. extending responses
Possible values
addressaddressescharge_activitiescustomereventevent_chargemetafieldspayment_methodssubscriptions
topicstring
The event that will trigger the webhook.
versionstring
The version of the API used to populate the body of the webhook. For V2, send v2 or 2021-11. Both are saved and returned as 2021-11.
Possible values
v22021-012021-11

RelatedExtending webhook responses →

PUT/webhooks/{id}

curl -X PUT 'https://api.rechargeapps.com/webhooks/958' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
  "address": "https://request.in/foo"
}'

Response

{
  "webhook": {
    "id": 6,
    "address": "https://request.in/foo",
    "topic": "subscription/created",
    "included_objects": [],
    "version": "2021-11"
  }
}

#Delete a webhook

DELETE/webhooks/{id}

Delete a Webhook

DELETE/webhooks/{id}

curl -X DELETE 'https://api.rechargeapps.com/webhooks/958' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

Response

{}

#List webhooks

GET/webhooks

Returns all the webhooks of the given store that are owned by the current requesting client (note that a a private token shows all of the store’s webhooks, an integration token only shows that integration’s webhooks).

Only webhooks created by the app that owns the token are returned. The response does not include next_cursor or previous_cursor; use limit and page to paginate.

Query parameters

limitintegerNew
Number of results to return. Defaults to 50; the maximum is 250.
pageintegerNew
Page to show. Cannot be greater than 300. Page-based pagination can be disabled for a token, in which case cursors must be used.
sort_bystringNew
Sort order of the results. Defaults to id-desc.
Possible values
id-ascid-desc

GET/webhooks

curl 'https://api.rechargeapps.com/webhooks' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

Response

{
  "webhooks": [
    {
      "id": 19451,
      "address": "https://request.in/foo",
      "included_objects": [],
      "topic": "subscription/created",
      "version": "2021-11"
    },
    {
      "id": 19453,
      "address": "https://request.in/foo",
      "included_objects": [],
      "topic": "subscription/cancelled",
      "version": "2021-11"
    }
  ]
}

#Test webhooks

POST/webhooks/{id}/test

In order to test webhook connectivity, you can trigger the dispatch of a test webhook with our webhook test endpoint. Sending a POST request to the webhook endpoint containing a webhook id will dispatch an empty webhook body to the specified webhook’s destination url.

Returns 200 with the plain-text body ok. No request body is required.

POST/webhooks/{id}/test

curl -X POST 'https://api.rechargeapps.com/webhooks/<webhook_id>/test' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{}'

Response

{}