Webhook endpoints

#The webhook endpoint object

A webhook endpoint is an address that receives your events. Endpoints you add here are the same ones you see and manage in Developers, with the same rules: each mode has its own endpoints, up to 10 of them, each at a different address.

{
  "id": "we_N8nQ4vRx7KtZ2mLp9WcB",
  "object": "webhook_endpoint",
  "url": "https://automation.example.com/webhook/railbed-orders",
  "description": "n8n: Fulfil paid orders",
  "events": [
    "payment.paid",
    "payment.held"
  ],
  "livemode": false,
  "mode": "test",
  "previous_secret_expires_at": null,
  "created": 1790380525
}

#Create a webhook endpoint

POST/v1/webhook_endpoints

Adds an endpoint in the key's mode and returns it with its signing secret. Events start arriving with the next payment change.

curl https://pay.railbed.io/v1/webhook_endpoints \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://automation.example.com/webhook/railbed-orders",
    "description": "n8n: Fulfil paid orders",
    "events": ["payment.paid", "payment.held"]
  }'

const endpoint = await fetch('https://pay.railbed.io/v1/webhook_endpoints', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://automation.example.com/webhook/railbed-orders',
    description: 'n8n: Fulfil paid orders',
    events: ['payment.paid', 'payment.held'],
  }),
}).then((r) => r.json());
// Save endpoint.id and endpoint.secret now: the secret isn't returned again.

endpoint = requests.post(
    "https://pay.railbed.io/v1/webhook_endpoints",
    headers={"Authorization": f"Bearer {os.environ['RAILBED_SECRET_KEY']}"},
    json={
        "url": "https://automation.example.com/webhook/railbed-orders",
        "description": "n8n: Fulfil paid orders",
        "events": ["payment.paid", "payment.held"],
    },
    timeout=15,
).json()
# Save endpoint["id"] and endpoint["secret"] now: the secret isn't returned again.

{
  "id": "we_N8nQ4vRx7KtZ2mLp9WcB",
  "object": "webhook_endpoint",
  "url": "https://automation.example.com/webhook/railbed-orders",
  "description": "n8n: Fulfil paid orders",
  "events": [
    "payment.paid",
    "payment.held"
  ],
  "livemode": false,
  "mode": "test",
  "previous_secret_expires_at": null,
  "created": 1790380525,
  "secret": "whsec_Tq7mVx2RkL9pZc4WbN8yHd3Jf6Gs1Ae0Ku5Xo-Pi_Mr"
}

The endpoint appears in Developers straight away, credited to the person who created the key (or approved the agent), and your account's activity records it with the key that added it. Keys created before October 9, 2026 don't record a creator, so their endpoints show no name.

#Retrieve a webhook endpoint

GET/v1/webhook_endpoints/:id

Returns one of your endpoints in the key's mode, without its secret. A removed endpoint, another account's, or one in the other mode is 404 not_found, so an automation tool can tell whether its subscription still exists.

curl https://pay.railbed.io/v1/webhook_endpoints/we_N8nQ4vRx7KtZ2mLp9WcB \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY"

#List webhook endpoints

GET/v1/webhook_endpoints

Returns your endpoints in the key's mode, newest first, without their secrets. Removed endpoints aren't listed.

curl https://pay.railbed.io/v1/webhook_endpoints \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY"

{
  "data": [
    {
      "id": "we_N8nQ4vRx7KtZ2mLp9WcB",
      "object": "webhook_endpoint",
      "url": "https://automation.example.com/webhook/railbed-orders",
      "description": "n8n: Fulfil paid orders",
      "events": [
        "payment.paid",
        "payment.held"
      ],
      "livemode": false,
      "mode": "test",
      "previous_secret_expires_at": null,
      "created": 1790380525
    }
  ],
  "has_more": false,
  "next_cursor": null
}

#Delete a webhook endpoint

DELETE/v1/webhook_endpoints/:id

Removes the endpoint: it stops receiving events and its pending retries stop. Its delivery history stays readable under Removed endpoints in Developers for 30 days. Deleting works even when the account is suspended or archived, as removing an endpoint in the dashboard does.

curl -X DELETE https://pay.railbed.io/v1/webhook_endpoints/we_N8nQ4vRx7KtZ2mLp9WcB \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY"

{
  "id": "we_N8nQ4vRx7KtZ2mLp9WcB",
  "object": "webhook_endpoint",
  "deleted": true
}

Deleting an endpoint that was already removed is 404 not_found; treat that as done.

#Access

These endpoints need the webhooks:read (retrieve, list) and webhooks:write (create, delete) scopes. Keys with Full access have both. Read only keys have neither, because an endpoint's address can carry its receiver's own token. Connected AI agents don't have them yet, so use a secret key.

#For automation tools

A tool that subscribes on a user's behalf (an n8n trigger, a Zapier REST hook, your own job runner) follows the same pattern:

1. When the user turns the automation on, create an endpoint with the tool's receiving address, the events it needs and a description naming the tool and the automation. Store the returned id and secret with the automation.
2. Verify every delivery's Railbed-Signature with that secret, as in Verify signatures, and answer 2xx quickly.
3. Before reusing a stored subscription, retrieve it by id. A 404 means it was removed (in Developers, or by another tool): create a new one.
4. When the user turns the automation off, delete the endpoint. A 404 means it's already gone.

Every endpoint counts toward the 10 per mode, including ones a tool forgot to delete. Remove stale ones in Developers, or list them here and delete the ones your tool created (its description tells you which).