Test Outbound Webhook Delivery

When you add outbound webhooks to your application, you're providing a powerful way for your users to integrate with your product. But before your users can start building on your webhooks, you need to be confident that they are reliable. Testing your entire webhook delivery pipeline is a critical step.

This guide walks you through how to test the outbound webhook functionality you've built with Hookdeck. You'll learn how to act as one of your own users to validate that events are sent correctly, that security features like signatures are working, and that your system gracefully handles delivery failures.

This guide assumes you have read the Send Webhooks with Hookdeck use case guide, which provides a complete overview of building outbound webhook capabilities.

How to test your webhook integration

Testing your integration ensures that your code correctly uses the Hookdeck API to create resources and publish events. The process involves acting as one of your users to register a test endpoint and trigger events, then verifying the results.

Create a test endpoint to inspect payloads

First, you need a URL that can receive webhooks so you can inspect their headers and payload. This simulates the endpoint your user would provide. You have a few options:

• Hookdeck Console: View the event in the Hookdeck Console. This is the simplest way to see the full request and response data.
• Public Bin Services: Use a service like webhook.site to get a temporary, public URL that displays all incoming requests.
• ngrok: Use the ngrok CLI to create a public tunnel to a simple web server running on your local machine.

Choose one of these options and get your test URL ready.

Register the test endpoint in your application

Now, act as a user of your own application. Go to the section of your UI where a user would register a new webhook endpoint and enter the test URL from the previous step.

When you save the endpoint, your application's backend should make an API call to Hookdeck to create a new Connection , which includes the Source for this user and the Destination with the test URL.

You can verify the Connection was created within the Hookdeck Dashboard or programmatically using the Connections endpoint.

Trigger an event in your application

Perform an action in your application that should trigger a webhook to be sent to the user you are impersonating. For example, if you have a note.created event, create a new note.

This action should cause your backend to make a request to the Hookdeck Publish API, sending the event data to the user's Source .

Verify the webhook delivery

Check your test endpoint (from step 1). You should see the webhook that Hookdeck delivered. Verify the following:

• The request body (payload) is correctly formatted and contains the data you expect.
• All expected HTTP headers are present, especially your webhook signature header if you are signing webhooks.
• Note any x-hookdeck-* headers. These can be white-labeled if you want to remove Hookdeck branding.

Test your failure and retry logic

A critical part of testing is ensuring your integration handles failures correctly.

1. Simulate a Failure: Register a new endpoint for your test user, but this time use a URL that you know will fail, such as https://httpstat.us or a non-existent domain.
2. Trigger an Event: Send another event from your application.
3. Verify Retries and Issues: Go to the Hookdeck dashboard. You should see the event delivery failing. Check the Attempts to confirm that Hookdeck is retrying the delivery based on the retry schedule you configured. Confirm that Hookdeck creates an Issue based on your Issue Trigger criteria. This confirms that your monitoring and alerting foundation is working correctly.

Monitoring outgoing webhook delivery with Hookdeck

Hookdeck's observability features are not just for inbound webhooks; they are equally powerful for monitoring the webhooks you send to your users.

Event logs

The Events page is your primary tool for real-time monitoring. You can filter the event stream by a specific Destination (representing a user's endpoint) to inspect individual delivery Attempts . This allows you to see the exact status code, headers, and response body returned by the user's server for each attempt.

Issues and alerting

Configure Issue Triggers on the Connections that send webhooks to your users. When a user's endpoint consistently fails, Hookdeck will automatically create an Issue and notify you via your configured channels (e.g., Slack, email, webhook). The details within the Issue provide valuable context that you can use to help your user troubleshoot their endpoint.

By using webhook issue notifications, you can build custom logic to proactively alert your users about their failing webhook endpoints.

Metrics dashboard

Requires a Growth or Enterprise plan.

The metrics dashboard provides a high-level overview of your outgoing webhook performance. You can track key indicators like delivery success rates, error rates, and latencies for each Connection . This helps you quickly identify users or endpoints that are experiencing a high volume of failures.

Providing feedback to your users

When you detect a failing endpoint, it's important to provide clear and timely feedback to your users.

• Proactive Notifications: Use the notifications from Hookdeck's Issue Triggers to build a system that proactively emails users about their failing webhook endpoints.
• Programmatic Management: For advanced use cases, you can use the Hookdeck API to programmatically create and manage Issue Triggers for your users, tailoring the alerting rules to their specific needs. You can learn more in our API documentation for Issue Triggers.

Related Hookdeck features & documentation

Send Webhooks Guide ->

Learn how to use Hookdeck to send webhooks to your users

Event Logs ->

Events are outgoing requests from Hookdeck.

Issues & Notifications ->

Track problems and communicate resolutions with your team.

Also see the Publish API Reference for details on how to publish events.