Webhook Relay Getting Started: Setup and First Request (2026)

Getting started overview

This guide outlines the essential steps to begin using Webhook Relay, focusing on account setup, credential generation, and executing a foundational request. Webhook Relay is designed to facilitate webhook management, including secure tunneling to local environments, debugging incoming requests, and ensuring reliable delivery to multiple endpoints. The process involves creating an account, obtaining necessary API credentials, and configuring a webhook bucket to receive and forward HTTP requests.

The initial setup can be summarized in a few key stages:

1. Account Creation: Register for a Webhook Relay account.
2. Credential Generation: Obtain an API access token from the dashboard.
3. Bucket Configuration: Create a webhook bucket, which serves as the public endpoint for incoming webhooks.
4. First Request: Send a test webhook to your newly created bucket to verify functionality.

This process enables developers to quickly establish a functional webhook endpoint for testing or integration purposes. The subsequent sections detail each of these steps, providing specific instructions and examples.

Quick reference table

Create an account and get keys

Access to Webhook Relay's services requires an account. Upon registration, you gain access to the dashboard where you can manage your webhooks, buckets, and API tokens. Webhook Relay offers a free tier that includes one bucket, one destination, and 200 messages per day, suitable for initial exploration and development.

Account registration

1. Navigate to the Webhook Relay website.
2. Click on the "Sign Up" or "Get Started Free" button.
3. Provide the required information, typically an email address and a password.
4. Complete any necessary email verification steps.

Generating API credentials

After creating your account and logging into the dashboard, you need to generate an API access token. This token authenticates your requests when interacting with the Webhook Relay API or CLI tools.

1. From the Webhook Relay dashboard, navigate to the "Tokens" section (usually found in the sidebar or user settings).
2. Click on "Create Token" or similar to generate a new access token.
3. Provide a descriptive name for your token (e.g., "My First API Token").
4. The system will display your new API token. Copy this token immediately, as it may not be displayed again for security reasons. Treat this token as sensitive information, similar to a password.

This token is crucial for authenticating when using the Webhook Relay CLI or integrating directly with their API. For example, when setting up a local tunnel, the CLI will require this token to establish a secure connection.

Your first request

To confirm your setup is functional, the next step is to create a webhook bucket and send a test request to it. A webhook bucket acts as a unique URL endpoint that receives incoming HTTP requests and can then forward them to one or more destinations.

Creating a webhook bucket

1. In the Webhook Relay dashboard, go to the "Buckets" section.
2. Click "Create Bucket" or a similar prompt.
3. Enter a unique name for your bucket (e.g., my-first-test-bucket). This name will form part of your public webhook URL.
4. Optionally, configure initial destinations for your bucket. For a simple first test, you can leave destinations empty or point it to a simple webhook logger like webhook.site for external verification.
5. After creation, Webhook Relay will provide you with a unique public URL for your bucket (e.g., https://my.webhookrelay.com/v1/webhooks/my-first-test-bucket). Copy this URL.

Sending a test webhook

You can send a test request using various methods. The cURL command-line tool is a common and straightforward option for HTTP requests, or you can use one of Webhook Relay's client SDKs.

Using cURL

Open your terminal or command prompt and execute the following command, replacing YOUR_BUCKET_URL with the URL you copied for your bucket:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello, Webhook Relay!"}' \
  YOUR_BUCKET_URL

This command sends a POST request with a JSON payload to your webhook bucket.

Using Python SDK

First, install the Python SDK:

pip install webhookrelay

Then, use the following Python code, replacing YOUR_ACCESS_TOKEN and YOUR_BUCKET_NAME:

from webhookrelay import WebhookRelay

client = WebhookRelay(api_token='YOUR_ACCESS_TOKEN')

try:
    # Get the bucket object
    bucket = client.get_bucket('YOUR_BUCKET_NAME')
    print(f"Bucket URL: {bucket.url}")

    # Simulate sending a webhook to this bucket (client-side simulation)
    # For actual external test, use cURL or another tool to hit the bucket.url
    print("To test, send a POST request to:")
    print(bucket.url)

except Exception as e:
    print(f"Error: {e}")

Note: The Python SDK example primarily interacts with the Webhook Relay API to manage buckets and streams. To *send* a webhook *to* the bucket's public URL, you would typically use an HTTP client like requests in Python, or curl, as shown above. The SDK is more for managing the Webhook Relay service itself.

Verifying the request

After sending your test request, navigate back to the Webhook Relay dashboard. Go to the "Buckets" section, select your bucket, and then click on "Messages". You should see your incoming request logged with its details, including the payload you sent. If you configured an external destination, verify the message arrived there as well.

Common next steps

Once you've successfully sent your first request, consider these common next steps:

• Local Development Tunneling: If you're developing locally and need to receive webhooks from external services, set up a local forwarding tunnel using the Webhook Relay CLI. This allows webhooks sent to your public bucket URL to be forwarded directly to your local machine.
• Add Destinations: Configure multiple destinations for your bucket. This allows you to fan out a single incoming webhook to several internal or external services simultaneously.
• Inspect and Debug: Utilize the dashboard's message inspection capabilities to view headers, payloads, and delivery statuses, which is useful for debugging integrations.
• Security: Implement webhook security measures such as signature verification or IP whitelisting to protect your endpoints. Services like Stripe and Twilio provide guidance on verifying webhook authenticity.
• Explore SDKs: Integrate Webhook Relay into your applications using one of the available SDKs for Go, Node.js, Python, or Ruby to programmatically manage buckets, destinations, and streams.

Troubleshooting the first call

If your first webhook call does not appear in the Webhook Relay dashboard or at your intended destination, consider these troubleshooting steps:

• Verify Bucket URL: Double-check that the URL you are sending the request to precisely matches the bucket URL provided in the Webhook Relay dashboard. Even minor typos can prevent delivery.
• HTTP Method: Ensure you are using the correct HTTP method (e.g., POST, GET) as expected by your webhook source or destination. Most webhooks use POST.
• Content Type Header: Confirm that the Content-Type header is correctly set, especially for JSON or XML payloads (e.g., application/json). Incorrect headers can cause parsing issues.
• Payload Format: Validate that your request payload is correctly formatted (e.g., valid JSON). Malformed payloads might be rejected or misprocessed.
• Dashboard Logs: Check the "Messages" tab for your bucket in the Webhook Relay dashboard. If the message appears there but not at your destination, the issue likely lies with the destination configuration or its availability.
• Destination Status: If you have configured a destination, ensure it is online and accessible from Webhook Relay. Check your destination's logs for any errors.
• Network Issues: Temporarily disable any local firewalls or VPNs if you are tunneling to a local development environment, to rule out network interference.
• API Token Permissions: If you are using the CLI or SDKs, ensure your API token has the necessary permissions. Although less common for basic forwarding, it can affect advanced configurations.
• Rate Limits: For free-tier users, check if you have exceeded the 200 messages/day limit. The dashboard should indicate your current usage.
• Consult Documentation: Refer to the official Webhook Relay documentation for detailed troubleshooting guides and common issues.