Webhooks troubleshooting guide
Troubleshooting guide when using webhooks.
If you find your app encountering one of the following scenarios, this guide will help you troubleshoot what may be wrong with your webhook setup.
Identify symptoms
For every scenario, see recommended section of investigation to start at in the following table:
| Scenario | Start investigation at ... |
|---|---|
| Never successfully received any webhook payload from Recharge. | Step 1 |
| Received successful webhook payload in the past but not for this new webhook. | Step 2 |
| Received successful webhook payload but has stopped since and has not resumed. | Step 2 |
| Received successful webhook payload but it temporarily stopped and then resumed. | Step 3 |
| Receiving successful webhook payloads but not as many as expected. | Step 4 |
| Receiving successful webhook payload but we are getting notifications of failures. | Step 5 |
| Webhook keeps being deleted | Step 5 |
Investigation
Step 1 - Check your settings
- Server settings
- Check your SSL certificate.
- Check you are not blocking Recharge IPs.
- Webhook settings Double check your webhook definitions :
Resolution
Ensure Recharge IP addresses are whitelisted on your server. Sanity check and correct address setup and token scopes.
If the issue does not resolve, move to the next steps of troubleshooting.
Step 2 - Check the webhook exists
Important:The list endpoint will only list the webhooks which exists for the token you are using so make sure you are using the same token you are expecting the webhook to be under or cycle through the tokens you use for webhooks if there are multiple.
If you do not find the webhook in the list of webhooks it means it was not set up successfully or has been deleted.
Reminder: cf. Webhook resources for more information on what qualifies as a "successful" webhook delivery.
Resolution
Create/re-create the webhook for the topic you are looking to listen to and sanity check the webhook has registered correctly by listing and testing your new webhook(s).
If the issue does not resolve, move to the next steps of troubleshooting.
Step 3 - Check service availability
If all setups are correct and have not changed and there has been a disruption in the deliverability of webhooks it can be linked to a temporary outage on the emitter (Recharge) or the listener (your app) or both.
First, try to identify the timeframe during which you stopped receiving the payloads and whether this affected all your webhooks or a limited number of them.
Then, check the services are up and running and whether they went through downtime during the downtime you have identified.
- Receiver - Make sure your app and address are available and did not encounter down time.
- Emitter - Check Recharge Status Page for any declared outage. If you don’t already subscribe to the Status page, it is recommended you sign-up. This will allow you to get immediate notification should any disruption to Recharge’s services occur.
You can also check the email address linked to your Webhooks’ API token(s) for any webhook submission failure notification received during this timeframe.
Resolution
Make sure all services on both ends are available.
Contact Recharge Support to help replay the events of the timeframe. Make sure that your app is set up to handle duplicate events.
Step 4 - Check you are set for the correct events
Recharge supports many topics which cover most of the customer, subscriptions and store lifecycle.
If you are receiving the payloads but less than what you expected:
- Make sure the topic you have chosen is indeed reflecting the lifecycle event you are looking to track. More details in webhook explained.
- Find an example:
- Check if you can either reproduce an example of the webhook event not being triggered upon action.
- Collect examples from support tickets or your app logs.
Resolution
If you find you are monitoring the wrong topic you can delete your existing webhook and setup a new one.
Contact Recharge Support to help replay the events of the timeframe. Make sure that your app is set up to handle duplicate events.
Step 5 - Check your response codes and timing
Recharge needs to receive a 200 response code from your app within 5s of sending the payload in order to acknowledge a successful delivery (cf. webhooks resources).
If you are receiving webhook events but your webhooks are getting repeatedly deleted check:
- Your response codes.
- Timing of your responses.
Resolution
Ensure correct response codes on webhook reception and ensure timely response
If you have run through all the troubleshooting steps above without success, escalate to Recharge Support and an agent will be in touch.
Escalation
After running through the troubleshooting steps, contact Recharge Support and share the following details:
- Store ID or URL
- Issue you are experiencing - point out of the ‘symptoms’.
- Webhook id or specify ‘all webhooks’ if all are failing
- Troubleshooting - highlight the troubleshooting steps you have already gone through so the agent does not ask you to do them again
- How this is impacting your app
- Any other details you feel is relevant
Updated 8 months ago