Getting started

Quickstart

Go from zero to a verified, retried, observable webhook in about five minutes. Examples are shown in curl, Python and Node.js.

The examples use https://api.hookflow.dev and https://in.hookflow.dev as base URLs — replace them with your workspace's endpoints.

Get an access token

Every request to the management API needs a token. Exchange your credentials for one, or create a long-lived API key under Settings → API keys in the dashboard.

curl -X POST https://api.hookflow.dev/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "password": "••••••••"}'

import requests

r = requests.post("https://api.hookflow.dev/api/v1/auth/token",
                  json={"email": "you@company.com", "password": "••••••••"})
token = r.json()["access_token"]

const res = await fetch("https://api.hookflow.dev/api/v1/auth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "you@company.com", password: "••••••••" }),
});
const { access_token: token } = await res.json();

Create an endpoint

An endpoint tells HookFlow where to forward events. Pick the provider so signatures are verified with the right scheme.

curl -X POST https://api.hookflow.dev/api/v1/endpoints \
  -H "Authorization: Bearer $HOOKFLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "billing-events", "provider": "stripe",
       "url": "https://api.example.com/webhooks/stripe"}'

endpoint = requests.post(
    "https://api.hookflow.dev/api/v1/endpoints",
    headers={"Authorization": f"Bearer {token}"},
    json={"name": "billing-events", "provider": "stripe",
          "url": "https://api.example.com/webhooks/stripe"},
).json()
print(endpoint["id"], endpoint["ingest_url"])

const endpoint = await fetch("https://api.hookflow.dev/api/v1/endpoints", {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "billing-events", provider: "stripe",
                         url: "https://api.example.com/webhooks/stripe" }),
}).then(r => r.json());
console.log(endpoint.id, endpoint.ingest_url);

Point your provider at HookFlow

Copy the ingest_url from the response into your provider's webhook settings. For Stripe that's Developers → Webhooks → Add endpoint. Custom sources can post to /hooks/custom/{token} using the token shown on the endpoint.

# Provider-specific ingest URLs
https://in.hookflow.dev/hooks/stripe
https://in.hookflow.dev/hooks/github
https://in.hookflow.dev/hooks/shopify
https://in.hookflow.dev/hooks/custom/<endpoint-token>

Send a test event

Fire a test event. You'll get an event ID back immediately; HookFlow forwards it to your URL in the background.

curl -X POST https://in.hookflow.dev/hooks/stripe \
  -H "Content-Type: application/json" \
  -d '{"id": "evt_test", "type": "invoice.paid"}'

# => {"received": true, "id": "evt_4f1c9a2b7e3d6058"}

r = requests.post("https://in.hookflow.dev/hooks/stripe",
                  json={"id": "evt_test", "type": "invoice.paid"})
print(r.json())  # {'received': True, 'id': 'evt_...'}

const r = await fetch("https://in.hookflow.dev/hooks/stripe", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ id: "evt_test", type: "invoice.paid" }),
});
console.log(await r.json());

Watch it arrive

List recent deliveries for the endpoint to confirm it arrived, and check status codes and latency. The same data drives the dashboard.

curl "https://api.hookflow.dev/api/v1/endpoints/$ENDPOINT_ID/deliveries?limit=5" \
  -H "Authorization: Bearer $HOOKFLOW_TOKEN" | jq '.data[] | {id, status, latency_ms}'

deliveries = requests.get(
    f"https://api.hookflow.dev/api/v1/endpoints/{endpoint['id']}/deliveries",
    headers={"Authorization": f"Bearer {token}"}, params={"limit": 5},
).json()["data"]
for d in deliveries:
    print(d["id"], d["status"], d["latency_ms"])

const { data } = await fetch(
  `https://api.hookflow.dev/api/v1/endpoints/${endpoint.id}/deliveries?limit=5`,
  { headers: { Authorization: `Bearer ${token}` } },
).then(r => r.json());
data.forEach(d => console.log(d.id, d.status, d.latency_ms));

Next: secure your consumer

Verify HookFlow's signature on every forwarded request.

Authentication guide →