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

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.

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 event 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 custom a 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.

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

Endpoints

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

#The Webhook object

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
addressescollectionscustomermetafields
topicstring
The event that will trigger the webhook.

RelatedExtending webhook responses →

The Webhook object

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

#Available webhooks

The list of all available webhooks.

Object	Topics	Scope Required
`Address`	`address/created` `address/updated`	read_customers
`Async_batch`	`async_batch/processed`	read_batches
`Customer`	`customer/activated` `customer/created` `customer/deactivated` `customer/payment_method_updated` `customer/updated`	read_customers
`Charge`	`charge/created` `charge/failed` `charge/max_retries_reached` `charge/paid` `charge/refunded` `charge/uncaptured` `charge/upcoming` `charge/updated`	read_orders
`Checkout`	`checkout/created` `checkout/completed` `checkout/processed` Note: Deprecated and not available for the Shopify integration with Shopify hosted Checkout (aka SCI)	read_orders
`Onetime`	`onetime/created` `onetime/deleted` `onetime/updated`	read_subscriptions
`Order`	`order/cancelled` `order/created` `order/deleted` `order/processed` `order/upcoming` `order/updated`	read_orders
`Product`	`product/created` `product/deleted` `product/updated`	read_products
`Subscription`	`subscription/activated` `subscription/cancelled` `subscription/created` `subscription/deleted` `subscription/skipped` `subscription/updated` `subscription/unskipped` `subscription/paused`	read_subscriptions
`Shop`	`app/uninstalled`	read_store
`Recharge`	`recharge/uninstalled`	store_info

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

Body parameters

addressintegerRequired
The URI where the webhook should send the POST request when the event occurs.
included_objectsarray
List of objects to enrich the webhook payload. cf. extending responses
Possible values
addressescollectionscustomermetafields
topicintegerRequired
The event that will trigger the webhook.

RelatedExtending webhook responses →

POST/webhooks

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

Response

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

#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-Access-Token: your_api_token'

Response

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

#Update a webhook

PUT/webhooks/{id}

Updates Webhook

Body parameters

addressstring
The URI where the webhook should send the POST request when the event occurs.
topicstring
The event that will trigger the webhook.
included_objectsarray
List of objects to enrich the webhook payload. cf. extending responses
Possible values
addressescustomercollectionsmetafields

RelatedExtending webhook responses →

PUT/webhooks/{id}

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

Response

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

#Delete a webhook

DELETE/webhooks/{id}

Delete a Webhook

DELETE/webhooks/{id}

curl -X DELETE 'https://api.rechargeapps.com/webhooks/19451' \
  -H 'X-Recharge-Access-Token: your_api_token'

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 hooks, an integration token only shows that integration’s webhooks).

Scoperead_orders

GET/webhooks

curl 'https://api.rechargeapps.com/webhooks?limit=3' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

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

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

POST/webhooks/{id}/test

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

Response

{}