Testing webhooks

Learn how to test your webhooks and your code that handles webhook deliveries.

In this article

About testing webhooks

You can test webhook delivery. This will let you verify that GitHub sends a webhook delivery in response to an event that you expect to trigger a webhook delivery.

You can also test your code that handles webhook deliveries by using your computer or codespace as a local server and forwarding webhook deliveries to your local server. This will let you develop and debug your code without deploying your code to your production server.

Testing webhook delivery

You can trigger a webhook event and verify that GitHub sent a webhook delivery.

  1. Trigger your webhook. For example, if you are testing a repository webhook that is subscribed to the issues event, open an issue in the repository where the webhook is configured.

    You can also redeliver a previous webhook delivery. For more information, see Redelivering webhooks.

    If you are using an organization or repository webhook, you can also use the REST API to trigger the ping event for your webhook. If you are using a repository webhook and your webhook is subscribed to the push event, you can use the REST API to trigger a test push event for your webhook. For more information, see REST API endpoints for repository webhooks and REST API endpoints for organization webhooks.

  2. Check GitHub to verify that a webhook delivery was sent. For information about how to do this for each webhook type, see Viewing webhook deliveries.

If a webhook delivery was not sent, or if a webhook delivery was sent but GitHub indicates that the delivery failed, refer to the troubleshooting guide to help diagnose the problem. For more information, see Troubleshooting webhooks.

Testing webhook code locally

In order to test your webhook code locally on your computer or codespace, you can use a webhook proxy URL to forward webhooks from GitHub to your computer or codespace. You can use your computer or codespace as a local server to receive these forwarded webhooks.

The following sections demonstrate how to use smee.io to provide a webhook proxy URL and forward webhooks.

For specific examples of code and testing steps, see Handling webhook deliveries.

Get a webhook proxy URL

  1. In your browser, navigate to https://smee.io/.
  2. Click Start a new channel.
  3. Copy the full URL under "Webhook Proxy URL". You will use this URL in the following setup steps.

Configure a webhook to use the webhook proxy URL

Configure your webhook to use the webhook proxy URL from above. For more information, see Creating webhooks and Editing webhooks.

Now, GitHub will send webhook deliveries to that URL.

Start a local server

On your computer or codespace, start a local server. The way that you do this depends on how your code to receive webhooks is written. For examples, see Handling webhook deliveries.

You should make sure that your code can run locally. For example, if your code relies on environment variables on your server in production, you should make sure that the environment variables are also available on your local server.

You may also find it useful to add log statements so that you can verify that steps of your code executed as expected.

Keep your local server running while you test out your webhook.

Forward webhooks

  1. If you don't already have