Developing with webhooks can be a new experience for developers. It can be hard to debug when something goes awry. This guide will cover the basics for debugging and help you to direct your attention to the correct spot.

Understanding webhooks and local development

When you or a user of your application performs certain actions, a webhook can be triggered. You can see the full list of webhook events to see the various actions that could result in a Webhook. Depending on the events subscribed to in the Webhook section(opens in a new tab) of your dashboard, a webhook will be triggered.

When you are developing on your localhost, your application is not internet facing. It can't receive the webhook request. You will need to use a tool that creates a tunnel from the internet to your localhost. These tools will provide temporary or permanant URLs depending on the tool and the plan you subscribe to. Popular tools included ngrok, localtunnel and Cloudflare Tunnel.

Below is an image demonstrating the flow from when you perform an action that triggers a webhook through until the webhook is received by your application

FLOW CHART IMAGE HERE

Debugging

With the Webhook flow in mind, the following areas could cause problems when trying to develop with webhooks:

1. The webhook route is not correctly configured
2. Configuration in your dashboard
3. The tunnel being used
4. Verification of the webhook
5. The logic you created to process the webhook

Testing your Webhook route locally

If you are having trouble with your webhook, you can create a basic response and then test it locally. First, add the following file and code to your app. Also make sure that you add ignoredRoutes: ['/api/webhooks(.*)'] to your authMiddleware().

app/webhooks/test/route.ts
export async function POST() {
   return Response.json({ message: 'The webhook route is working' });
}

While your application is running, try this from the command line.

curl -H 'Content-Type: application/json' \
     -X POST http://localhost:3000/api/webhooks/test

If you see the {"message":"The webhook route is working"} then the basic webhook route is working, and ready to build on.

Configuration in your dashboard

Whether you are developing locally or deploying to production, the webhook URL provided must be exact and correct. The URL breaks down into three parts -- the protocol (http vs https), the domain (domain.com) and the path (/api/webhooks/user).

• Whether in development using a tunnel or in production, the URL will almost always use https.
• The domain needs to be exact. A common error in production is not including the www.. Unlike entering a domain in your browser, a webhook will not be redirect from domain.com to www.domain.com. If your application lives on www.domain.com then the webhook URL must use that.
• The path must match the path in your application.

Debugging your tunnel

You've setup your route and tested it, configured your tunnel, updated your dashboard and now are trying to use the webhook but are getting errors. You will want to visit the Webhook section(opens in a new tab) of your dashboard and the select the webhook you created.

You will see a 'Webhook Attempts' section and likely see that one or more of those attempts have failed. Click on the failed attempt to expand it. In the details for the attempt, there will be a 'HTTP RESPONSE CODE'. The code will likely be either a 500 or something starting with a 4, like 401 or 404. See HTTP response status codes(opens in a new tab) from MDN for reference.

IMAGES FROM THE WEBHOOK SECTION HERE

Below is a table with some of the common response codes you might see, and what they indicate:

You may run into other errors. A 4xx error will indicate there is some misconfiguration in the configuration.

Debugging the verification process

To verify the webhook, your webhook route will need the Signing Secret from the Webhook section of the dashboard as well of the Svia headers which are included in the request. Please see Create the endpoint in your application for details code examples. You can also visit the guide(opens in a new tab) on verifying webhooks with the Svix library.

Diagnosing a problem in this part of the webhook can be challenging. Your best get would be the liberal use of console.log. You could log out the following to check if the values are correct:

• the signing secret
• the headers
• the body before verifying
• the result of the .verify() attempt

The results of these will appear in the command line where you are running your application.

Checking the values and the progress of the webhook code will allow you to narrow down where the code is failing. The will often return null or errors where they should be returning values.

Debugging your logic

Once you have verified the webhook, you will now be writing your own code to handle the values from the webhook. This could range from saving data to a databse, or integrating with another system, to updating users or sending emails or SMS. If the webhook is verified and you are seeing a 500 status code or your webhook is not behaving as expected, remember that you can use console.log to help diagnose what the problem is. Console logs and error will be displayed on your command line, allowing you to see what's happening and address the bugs.