Using webhooks

Uses

Use webhooks to collect data from the Recharge API and create a variety of custom solutions. For example, you can build custom dashboards that use webhook callback data to show information about customer purchases. Data from webhook callbacks can be used to create analytics reports store owners can use to improve the shopping experience. Your application can be reactive to Recharge's webhooks and take follow up actions like updating a subscription product when customers add it to cart.

Example workflow

If you offer a subscription where the product a customer receives should change every month, your application can listen for the order/created callback and when it receives it, make a REST API call to change the product belonging to that subscription.

Webhooks explained

Handling the callback request

Callback payloads are identical to Recharge's REST API payloads. For example, the callback for the subscription/created webhook will be identical to the payload of a GET request to the subscriptions/<subscription_id> endpoint.

You should acknowledge you've received Recharge's webhook callback by sending a 200 OK response. Recharge will act as though you did not receive the callback if Recharge doesn't receive a response, or receives 408, 429 status codes, or a 500 or higher status code. Recharge's server waits 5 seconds for a response. If we do not receive a response in that period we consider the request failed. Recharge's system will attempt to send the same webhook 20 times over 48 hours (or two days). If the request fails each time or within this timeframe, we will delete this webhook from our system. At present we also log these deleted webhooks in our system.

🚧

Note:

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

Testing webhooks

We have set up a request bin that will allow you to test if your webhooks are triggered correctly.
Find out more on Recharge Bin page.

Validating webhooks

Webhooks created through the API can be verified by calculating a digital signature. Each Webhook request includes an X-Recharge-Hmac-Sha256 header which is generated using the API Client Secret, along with the data sent in the request.

API Client Secret is not the same as your API token and it can be found at:
Recharge Dashboard—>Integrations—>API Tokens—>Click on your token
Edit API Token page will appear and there you will find API Client Secret
request_body must be in JSON string format. Validation will fail even if one space is lost in process of JSON string generating.

The following are examples of validation codes:

echo -n '<client secret string here><request body here>' | openssl dgst -sha256

!IMPORTANT! client secret string needs to be concatenated with request body string
!and placed before it in order for validation to work!

import hashlib

def isWebhookValid():

    client_secret = "< Secret Client Token here >"
    request_body = "< request body here >"
    webhook_hmac = "< Hmac-Sha256 value from webhook response header here >"

    calculated_hmac = hashlib.sha256()
    calculated_hmac.update(client_secret.encode("UTF-8"))
    calculated_hmac.update(request_body.encode("UTF-8"))
    calculated_hmac = calculated_hmac.hexdigest()

    if calculated_hmac == webhook_hmac:
        print("Webhook validated successfully!")
        return True

    else:
        print("Oops! There may be some third party interference going on.")
        return False

isWebhookValid() #call the function

#IMPORTANT! adding client_secret after req_body to calculated_hmac
#will result in fake false, so make sure you update client_secret first
#and then req_body

<?PHP
function isWebhookValid()
{
    $client_secret = '< client secret string here >'
    $request_body = '< request body here >';

    $calculated_digest = hash('sha256',$client_secret.$request_body);

    $received_digest='< Hmac-Sha256 value from webhook response header here >';

    print("\n".$received_digest. "   RECEIVED\n");
    print($calculated_digest. "   CALCULATED\n");

    if (hash_equals($received_digest,$calculated_digest))
    {
        print("Webhook validated successfully!\n");
        return True;
    }
    else
    {
        print("Oops! There may be some third party interference going on.");
        return False;
    }
}
isWebhookValid();
?>

require 'digest'

def isWebhookValid()
    secret = '< secret client token here >'
    request_body = '< request body here >'
    received_digest = '< Hmac-Sha256 value from webhook response header here >'

    calculated_digest = Digest::SHA256.hexdigest(secret+request_body)

    print(calculated_digest +"\n")
    print(received_digest +"\n\n")
    if calculated_digest == received_digest
        print("VALIDATION SUCCESS!\n")
        return true
    else
            print("Oops! There may be some third party interference going on.\n")
        return false
    end
end
isWebhookValid()

Webhook FAQs

Webhook is not working

I’m not receiving any data from your webhook. When you are not receiving data from the webhook the issue can be both on our end and on your end. Refer to the following steps to identify which side the issue is coming from.

1. Create a request bin. You will use it to capture webhook data

2. Create the desired webhook and as address put your newly created request-bin.

3. Trigger the webhook with the specific action to that webhook.

4. Navigate to your request bin in the browser and check if any data has been received in the bin.

If you see new data in the request bin that means that the webhooks are working but your server or security settings on your end are blocking the request.

If you don’t see new data in your request bin, please contact Recharge support.

Is there a webhook I can use to be notified when a user skips a date on the front end?

subscription/skip and subscription/unskipped will trigger when you skip or unskip subscription within Charge.

More details on available webhooks in our API reference

When are webhooks automatically disabled?

When a webhook has posted to your server for several times, and failed every time, our system will automatically delete it.

Also, if the response time is too long, our system will automatically delete the webhook.

How can I test if my webhook charge/created triggered properly?

You can use our a request bin.

You can make a test subscription, than cancel your subscription and reactivate it (which would delete and create a charge).
If you don’t see the webhook then it’s an issue on our side, and we can pick it up and investigate the bug by doing the same and seeking to verify.
But, if you don’t see the webhook there, then it may be an issue in your code.