Getting Started with FirmHook

FirmHook is a webhook delivery platform. You point external services at your FirmHook ingest URL, and FirmHook handles routing, delivery, retries, and observability for you.

1. Sign up

Go to firmhook.com and create an account with your email address. You'll receive a verification email — click the link to activate your account before logging in.

2. Log in

Once verified, log in at firmhook.com/login.

3. Create an organization

Organizations are workspaces that group your sources, endpoints, events, and team members. On first login you'll be prompted to create one.

Note: The slug is permanent and cannot be changed after creation — choose carefully.

4. Create an API key

FirmHook uses API keys to authenticate ingest requests. Without a valid key, any request to your ingest URL is rejected.

1. 1Go to API Keys in the sidebar
2. 2Click Create API Key and give it a label (e.g. GitHub, Stripe)
3. 3Copy the key immediately — it is only shown once

Your key will look like this:

whq_sMU4YJbcEm22i-ddbVlkt30mL9-tn_74rsv4...

5. Create a source

A source represents an external service that sends webhooks to FirmHook. Each source has a unique ingest URL that you give to the sender.

1. 1Go to Sources in the sidebar
2. 2Click + Create Source
3. 3Fill in the details:

1. 1Click Create Source

After creation, copy the ingest URL — this is the URL you will give to the external service:

https://{org_slug}.firmhook.com/{source_id}

6. Create an endpoint

An endpoint is a destination on your server that FirmHook will forward incoming webhooks to.

1. 1Go to Endpoints in the sidebar
2. 2Click + Create Endpoint
3. 3Fill in the details:

The following fields are optional and can be configured now or later:

1. 1Click Create Endpoint

7. Optional: create a payload transformation

Payload transformations let you reshape webhook data before it is delivered to an endpoint. Use them when a destination expects different field names, needs sensitive fields removed, or requires extra metadata.

1. 1Go to Transformations in the sidebar
2. 2Click Create Transformation
3. 3Write a JavaScript function named transform
4. 4Test it with a sample payload
5. 5Attach it to an endpoint from the endpoint's Transformation field

Example:

javascript
function transform(payload, headers) {
  return {
    ...payload,
    delivered_by: "firmhook",
    transformed_at: new Date().toISOString(),
  }
}

The returned object becomes the payload FirmHook sends to the endpoint. If no transformation is selected, the original payload is delivered unchanged.

8. Create a routing rule

A routing rule connects a source to an endpoint. When a webhook arrives at a source's ingest URL, FirmHook evaluates all active routing rules for that source and delivers the event to every matched endpoint (fanout).

1. 1Go to Routing Rules in the sidebar
2. 2Click + Create Rule
3. 3Select the Source and Endpoint you created above
4. 4Optionally add filter conditions to route only specific events — for example, only route events where $.event_type equals push, or $.data.amount is greater than 100
5. 5Leave filters empty to route all events from the source to the endpoint

Tip: You can create multiple routing rules for the same source to fan out to different endpoints — for example, send all events to Production and only push events to a separate Audit endpoint.

An event with no matched routing rules is immediately marked dead (nowhere to deliver). Make sure at least one routing rule is active for each source.

9. Configure your external service

Give the external service (e.g. GitHub, Stripe, or your own app) the ingest URL from step 5 and your API key from step 4:

• Webhook URL — your ingest URL from step 5
• Header - X-Webhook-Api-Key: <your-api-key>

The external service will send requests like this:

http
POST https://acme-corp.firmhook.com/<source-id>
X-Webhook-Api-Key: whq_your_api_key_here
Content-Type: application/json

{
  "event": "order.created",
  "data": { ... }
}

FirmHook will evaluate your routing rules, fan out to all matched endpoints, and retry automatically on failure.

10. Monitor your webhooks

Once events start arriving, you can track them in the dashboard:

• Events — see every incoming webhook and its aggregate delivery status (pending, processing, delivered, partial, dead). A partial status means some endpoint chains succeeded and others failed.
• Event timeline — click any event to see a per-endpoint timeline. Each matched endpoint has its own chain showing every delivery attempt, response code, and AI-generated error explanation.
• Replay — manually re-deliver any event from the event detail page. You can replay to all endpoints or to a specific failed chain only.