Quickstart

In about ten minutes you will have a project, an API key, and an event delivered to a URL of yours, with every attempt on the record.

1. Get an instance

   Railhook Cloud

   Sign up at railhook.io/register. It is free right now on the Free plan: 10,000 events a month, 3 projects, 5 endpoints per project and 7 days of history. Paid plans with support and higher limits will come later.

   Your API base URL is https://railhook.io.

   Self-hosted

   On a machine with Docker:

   curl -fsSL https://railhook.io/install.sh | bash

   The installer checks the machine, writes a Compose file and a .env with generated secrets to ~/railhook, and starts the stack. Open http://localhost and register. No mail server is configured yet, so the first account is active straight away.

   Your API base URL is http://localhost — or http://localhost:<port> if you installed with --port.

2. Create a project and an API key

   In the dashboard, create a project, then open API Keys and create a key with the READ_WRITE scope. The key is shown once. Only its hash is stored, so copy it now.

3. Add an endpoint and subscribe it

   Open Endpoints and add the URL that should receive the webhook. Then open Subscriptions and subscribe that endpoint to the event type order.completed.

   Caution

   Railhook refuses to deliver to private and internal addresses by default. Use a URL that is reachable from the public internet.

4. Send an event

   cURL

   export RAILHOOK_URL=https://railhook.io   # or your own instance, e.g. http://localhost or https://hooks.example.com
   export RAILHOOK_API_KEY=...
   
   curl -X POST "$RAILHOOK_URL/api/v1/events" \
     -H "X-API-Key: $RAILHOOK_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: order-12345-completed" \
     -d '{"type":"order.completed","data":{"orderId":"ord_12345","amount":99.99}}'

   Node.js

   import { Railhook } from '@railhook/node';
   
   const client = new Railhook({
     apiKey: process.env.RAILHOOK_API_KEY,
     baseUrl: process.env.RAILHOOK_URL,
   });
   
   const event = await client.events.send({
     type: 'order.completed',
     data: { orderId: 'ord_12345', amount: 99.99 },
   });
   console.log(event.eventId, event.deliveriesCreated);

   Python

   import os
   
   from railhook import Railhook, Event
   
   client = Railhook(
       api_key=os.environ["RAILHOOK_API_KEY"],
       base_url=os.environ["RAILHOOK_URL"],
   )
   
   event = client.events.send(
       Event(type="order.completed", data={"order_id": "ord_12345", "amount": 99.99})
   )
   print(event.event_id, event.deliveries_created)

   PHP

   <?php
   use Railhook\Railhook;
   
   $client = new Railhook(
       apiKey: getenv('RAILHOOK_API_KEY'),
       baseUrl: getenv('RAILHOOK_URL'),
   );
   
   $event = $client->events->send(
       type: 'order.completed',
       data: ['orderId' => 'ord_12345', 'amount' => 99.99],
   );
   echo $event['eventId'];

   Railhook answers 201 with the eventId and deliveriesCreated: one delivery per matching subscription. The sending happens afterwards, not during your request.

5. See it delivered

   Open Deliveries. Each delivery shows its attempts and the status code and response body your endpoint returned. A 2xx marks it SUCCESS. Anything else is retried, and a delivery that runs out of attempts moves to Failed Messages.

Next steps

Send your first webhookThe same flow through the API, with signature checks on the receiving side.

Receive your first webhookTake in webhooks from Stripe, GitHub and others and forward them to your services.

ConceptsEvent, endpoint, delivery, attempt: the words the rest of the docs use.