Getting Started: Your First Webhook

Welcome to HookMux! This guide will walk you through the entire "golden path" from receiving your first webhook to debugging its delivery in under 5 minutes.

The goal is to receive a webhook from a service (like Stripe or GitHub) and reliably "fan it out" to multiple endpoints, like your app's API and a Slack channel.

Core Concepts

Before we start, let's learn two key terms:

  • Source: A Source is a unique, public-facing URL you create on HookMux. You give this URL to webhook senders (e.g., Stripe, GitHub, Shopify). This is the "ingest" point.
  • Destination: A Destination is a single, private endpoint URL (e.g., your API, a Slack webhook URL) where you want HookMux to send the data after it's received by a Source.

A single Source can have many Destinations.

Step 1: Create a Source

This is the public URL that will receive all your webhooks.

  1. From the HookMux dashboard, navigate to Webhooks in the sidebar.
  2. Click the Create Webhook button.
  3. Give your Source a descriptive name, like Stripe - Production or GitHub - MyProject.
  4. Choose which HTTP Methods that do you want to serve. For the time being, only GET and POST are supported. More will be added in the future.
  5. Give your webhook a custom endpoint URL slug. Your URL slug must be unique, and if it happens that existing URL slug had already been taken, you will be warned. Leave empty if you want a randomly-generated URL slug.
  6. Click Create Webhook.
  7. You will be taken back to the Webhooks page. Click the "View" button on the Source that you just created.
  8. Copy the Ingest URL located under your source's name. It will look something like this:
    https://core.hookmux.com/ingest/your-unique-slug

Keep this URL handy. You will give this to the third-party service (e.g., Stripe) in place of your own application's URL.

Step 2: Add Your Destination(s)

Now, let's tell HookMux where to send the webhooks it receives.

  1. On the Webhooks page, click the "View" button to the newly created source.
  2. Click the "+ Add Destination" button
  3. In the URL field, paste the actual endpoint you want to send data to. For this test, you can use a free service like webhook.site.
    Example URL: https://api.my-app.com/webhooks/stripe
  4. In the Allowed HTTP Methods, choose which HTTP Methods that do you want to serve. For the time being, only GETand POST are supported. More will be added in the future.
  5. Click Create Destination.

That's it! You can repeat this process to add more destinations. When your Source URL receives an event, HookMux will now deliver it to all its active destinations simultaneously.

Step 3: Secure Your Destination (Custom Headers)

Most of your destinations (like your own API) are probably private and require an API key or token. The Custom Headers feature is essential for this.

  1. In the source page you opened in Step 2, find the newly created destination card, and click the expand button (noted with icon).

  2. Click at the "Custom Headers" accordion trigger to expand the custom headers settings.

  3. Now to start adding/updating/deleting the custom headers, click the menu button (the button) and click "Start Edit".

  4. Enter the name and value for the authentication your API needs.

    Example 1: Bearer Token

    • Name: Authorization
    • Value: Bearer your-secret-api-token-12345

    Example 2: API Key

    • Name: x-api-key
    • Value: my-secret-key
  5. Click Add.

Now, every request sent to this specific destination will include the header you configured. Your secrets are end-to-end encrypted at rest and are never viewable again.

Step 4: Test & Debug

  1. Go to your webhook provider (e.g., Stripe's "Webhooks" dashboard) and trigger a test event to be sent to your HookMux Ingest URL.
  2. In HookMux, navigate to your Source's Activity tab.
  3. You will see a new log entry appear. If it's green (Success), it means HookMux successfully delivered the webhook to your destination(s).
  4. Click the log entry to inspect the full Payload (what HookMux received) and the Response (what your server sent back, including status code, headers, and body).
  5. If a delivery fails, you can click the Replay button to resend the exact same event. This is incredibly useful for debugging without having to trigger the original action again.

Next Steps

You've successfully routed your first webhook! Now you can explore more advanced features:

  • Alerts: Get notified by email if a destination starts failing.
  • Rate Limiting: Protect your servers from surges by setting a max requests-per-second limit for any destination.