Documentation

The Doorbell Analogy

Imagine you order a pizza. You could keep opening the front door every 30 seconds to check if the delivery person is there. That would be exhausting (and weird).

Instead, the delivery person rings your doorbell when they arrive. You only have to respond when something actually happens.

A webhook works exactly the same way. Instead of your app constantly asking another service "did anything happen yet?", that service sends your app a message the moment something happens. It rings your doorbell.

How It Looks in Practice

Here is the basic flow. A provider (like Stripe, GitHub, or Shopify) sends a message to Webhook, and Webhook delivers it to your app.

A Real-World Example

Say you use Stripe to accept payments. When a customer pays you $50, Stripe sends a small message (called a payload) to a URL you provide. That message says something like:

{
  "type": "payment_intent.succeeded",
  "data": {
    "amount": 5000,
    "currency": "usd",
    "customer_email": "jane@example.com"
  }
}

Your app receives this and can then send a receipt, update a database, or do whatever you need. You never have to ask Stripe "did someone pay?" -- Stripe tells you.

Webhook sits between the services that send webhooks and your application. Think of it as a reliable, smart mailbox for your webhooks. Here is what it does in plain English:

• Catches every webhook so you never miss one, even if your app is temporarily down.
• Shows you exactly what was sent -- the full payload, headers, timestamps, everything. Great for debugging.
• Forwards webhooks to your app automatically, so your code gets the data it needs.
• Retries when delivery fails. If your server is down or returns an error, Webhook tries again using a sensible schedule. No events lost.
• Helps you diagnose problems. See delivery status, response codes, and timing so you can figure out what went wrong fast.
• Lets you replay events. Made a bug fix and need to re-process an event? One click and it is sent again.

1 Sign Up or Log In

If you do not have an account yet, head to the homepage and create one. If you already have an account, just log in.

2 Create a Project

Go to Integrations and pick the provider you want to receive webhooks from (for example, Stripe or GitHub). Click Quick Setup. This creates a project and gives you a unique webhook URL.

3 Copy Your Webhook URL

After setup, you will see a URL that looks like this:

https://webhook.sdnbros.app/p/<your-unique-token>

Copy it. This is the address where your provider will send webhooks.

4 Paste It in Your Provider

Go to your provider's dashboard (e.g., Stripe, GitHub) and find their webhook settings. Paste your Webhook URL there. See the Provider Guides below for step-by-step instructions.

5 Send a Test

Most providers have a "Send test webhook" button. Click it and then come back to the Events page. The event appears after it is received and processed. You can also test with curl:

curl -X POST https://webhook.sdnbros.app/p/<your-token> \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

6 Set Up Forwarding (Optional)

If you want Webhook to forward events to your own backend, go to Settings and enter a Destination URL (e.g., https://myapp.com/webhooks). Webhook will automatically send every incoming event to that address, with retries if it fails.

What is the CLI for?

The sdnbros CLI lets you manage webhook projects, inspect and replay events, forward webhooks to your local machine via tunnel, and more — all from your terminal.

Install

curl -sSL https://webhook.sdnbros.app/install.sh | bash

# Download the binary for your platform
curl -Lo sdnbros https://webhook.sdnbros.app/dl/v0.4.3-93762f3/sdnbros-linux-amd64
chmod +x sdnbros
sudo mv sdnbros /usr/local/bin/

irm https://webhook.sdnbros.app/install.ps1 | iex

# PowerShell
Invoke-WebRequest -Uri https://webhook.sdnbros.app/dl/v0.4.3-93762f3/sdnbros-windows-amd64.exe -OutFile sdnbros.exe
Move-Item sdnbros.exe C:\Users\$env:USERNAME\AppData\Local\Microsoft\WindowsApps\sdnbros.exe

Log In

Connect the CLI to your account:

sdnbros login

This opens a browser window for authentication. Once you approve, the CLI is connected. Check your session with:

sdnbros whoami

Manage Projects

sdnbros webhook projects                              # List all projects
sdnbros webhook projects create --name my-project      # Create a new project
sdnbros webhook projects show --project my-project     # Show project details
sdnbros webhook projects delete --project my-project   # Delete a project

View & Replay Events

sdnbros webhook events --project my-project              # List recent events
sdnbros webhook events --project my-project --state failed # Show only failed events
sdnbros webhook events inspect <event-id>                 # Full event detail (JSON)
sdnbros webhook events replay <event-id>                  # Re-deliver a failed event

Find event IDs on the Events page or from the list output above.

Local Tunnel (Forward to localhost)

Forward incoming webhooks to your local dev server:

sdnbros webhook tunnel --project my-project --port 8080 --path /webhook

Webhooks received by your project are forwarded to http://localhost:8080/webhook in real time. The tunnel auto-reconnects if the connection drops.

Set Destination

sdnbros webhook destination set --project my-project --url https://api.example.com/webhooks

Configure where webhooks are forwarded to in production.

Other Commands

sdnbros version                  # Check CLI version
sdnbros update                   # Update to latest version
sdnbros completion bash          # Generate shell completions
sdnbros logout                   # Clear stored credentials

How Forwarding Works

When you set a Destination URL in your project settings, Webhook forwards every incoming webhook to that URL. Your app receives the exact same payload and headers that the provider sent.

If your app responds with a 2xx status code (like 200 OK), the delivery is marked as successful. Anything else (or a timeout) is treated as a failure, and Webhook will retry.

The Retry Schedule

When delivery fails, Webhook does not give up. It tries again on this schedule:

That is 6 total attempts spread over roughly 5.5 hours. If the last attempt still fails, the event is marked as failed. You can always replay it manually later.

"I don't see my webhook"

• Check the URL. Make sure the URL you pasted in your provider exactly matches the one from your Webhook project. Even a small typo will break it.
• Check your provider config. Some providers require you to select specific event types. Make sure you have at least one event type selected.
• Try sending a test manually. Use the curl command from the Getting Started section. If that works, the issue is on the provider side.
• Check the right project. If you have multiple projects, make sure you are looking at the correct one in the Events page.

"Delivery keeps failing"

• Check your destination URL. Go to Settings and verify the forwarding URL is correct and reachable from the internet.
• Is your server actually running? Try opening the destination URL in a browser or hitting it with curl. If it does not respond, Webhook cannot deliver to it either.
• Check the response code. Click on a failed event in the Events page. The delivery details show the HTTP status code your server returned. A 500 means your server hit an error; a 404 means the URL path is wrong.
• Check for timeouts. Webhook waits up to 30 seconds for your server to respond. If your processing takes longer, return 200 immediately and process in the background.

"I hit my event limit"

When you reach your monthly event limit, new webhooks get a 429 Too Many Requests response. Your existing events are safe. To fix this, upgrade your plan for a higher limit.

"How do I replay a failed event?"

Go to the Events page, click on the failed event, and hit the Replay button. Or use the CLI: sdnbros webhook events replay <event-id>. Replay is available on Pro and Business plans.

"Where are my old events?"

Events remain available in the product based on your plan: 3 days on Free, 7 days on Starter, 30 days on Pro, and 1 year on Business. Periodic cleanup removes expired primary event rows, but object-storage copies, backups, and some derived records may remain longer. See the Privacy Policy.

Review currently available plans, included event limits, and retention on the Pricing page. Manage an existing subscription on the Billing page.