Quickstart

1. Get an instance

   Railhook Cloud

   Sign up at railhook.io/register. The Free plan gives 10,000 events a month, 3 projects, 5 endpoints per project and 7 days of history.

   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. With no mail server configured, 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).

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

   By default Railhook refuses private and internal addresses. Use a publicly reachable URL.

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). Sending happens after the request returns.

5. See it delivered

   Open Deliveries. Each delivery shows its attempts with your endpoint’s status code and response body. A 2xx marks it SUCCESS; anything else is retried, and a delivery out of attempts moves to Failed Messages.