Your First Webhook

Step-by-step tutorial — create a source, send a webhook, and inspect the event.

In this tutorial you'll create a source, send a webhook from your terminal, watch it appear in the dashboard in real time, and (optionally) wire up a destination for delivery. Total time: about three minutes.

Using the Dashboard

Create a source

Name: Tutorial Source
Verification: None (for this tutorial)

Click Create. You'll see your source's ingestion URL:

text
https://hookstream.io/v1/ingest/<source_id>

Copy it — you'll need it in the next step.

Send a webhook

Open your terminal and send a POST request:

curl -X POST https://hookstream.io/v1/ingest/<source_id> \
  -H 'Content-Type: application/json' \
  -d '{"event": "user.created", "user": {"id": "usr_42", "email": "alice@example.com"}}'

await fetch("https://hookstream.io/v1/ingest/<source_id>", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    event: "user.created",
    user: { id: "usr_42", email: "alice@example.com" },
  }),
});

import requests

requests.post(
    "https://hookstream.io/v1/ingest/<source_id>",
    json={
        "event": "user.created",
        "user": {"id": "usr_42", "email": "alice@example.com"},
    },
)

You should get a 200 OK response with an event_id in the JSON body.

Inspect the event

Head to Events in the dashboard. You'll see your event listed with the method, source, and timestamp. Click it to drill into:

Full request headers
Parsed JSON body
Query parameters
Metadata (source IP, content length, etc.)

If the dashboard is already open when you send the request, the event appears in real time via WebSocket push — no refresh needed.

Add a destination (optional)

To actually deliver events somewhere:

Go to Destinations > Create Destination
Choose HTTP/Webhook and enter your endpoint URL
Go to Connections > Create Connection
Select your source and destination
Send another webhook — watch it get delivered

Check the Events page to see delivery attempts with status codes and latency. If your endpoint is unreachable, hookstream will retry automatically with exponential backoff.

Using the CLI

You can do the entire flow from your terminal with the hookstream CLI:

bash
npm install -g @hookstream/cli
hookstream login

hookstream sources create "Tutorial Source"
hookstream destinations create "My Endpoint" --url https://example.com/webhook
hookstream connections create "My Pipeline" \
  --source <source_id> \
  --destination <dest_id>

# Send a webhook to the source URL, then check events:
hookstream events list

hookstream login opens your browser for a one-time device auth flow. If you're on a headless box, pass --no-browser to get the device code in the terminal instead.

You can also tail events live with hookstream listen — it opens a WebSocket and prints events as they arrive.