Create a webhook endpoint

curl -X POST https://api.runledger.co/v1/webhook_endpoints \
     -H "Authorization: Bearer <api_key>" \
     -H "Content-Type: application/json" \
     -d '{
  "url": "https://api.example.com/webhooks/runledger",
  "enabled_events": [
    "outcome_charge.reversed",
    "dispute.decision_due",
    "invoice.finalized"
  ]
}'

{
  "id": "we_7uI0oP3aSd",
  "object": "string",
  "url": "string",
  "enabled_events": [
    "string"
  ],
  "status": "enabled",
  "api_version": "2026-10-18",
  "metadata": {},
  "livemode": true,
  "created_at": "2024-01-15T09:30:00Z",
  "description": "string",
  "secret": "string",
  "last_success_at": "2024-01-15T09:30:00Z",
  "last_failure_at": "2024-01-15T09:30:00Z",
  "failing_since": "2024-01-15T09:30:00Z",
  "disables_at": "2024-01-15T09:30:00Z",
  "actor": {
    "type": "user",
    "id": "usr_4tN8vB2cXk",
    "name": "Claude Code",
    "on_behalf_of": "usr_4tN8vB2cXk",
    "client": "claude-code"
  }
}

Registers a URL to receive events. Deliveries follow the Standard Webhooks specification, so any Standard Webhooks library can verify them. The signing secret is returned only in this response and when you rotate it.

Authentication

AuthorizationBearer

A secret key (rl_sk_test_..., rl_sk_live_...) or a restricted key with limited scopes (rl_rk_test_..., rl_rk_live_...). A restricted key can carry agent: true and an expires_at, and is what a coding agent should hold. Keys end in a checksum so secret scanners can recognize them. People create, roll and revoke keys in the dashboard; GET /v1/api_keys lists them, masked.

Request

This endpoint expects an object.

urlstringRequiredformat: "uri"

An HTTPS URL.

enabled_eventslist of stringsRequired

Event types to send, or ["*"] for all.

descriptionstringOptional

metadatamap from strings to stringsOptional

Up to 50 keys of your own, with keys up to 40 characters and values up to 500 characters.

Response

The new endpoint, including its secret.

idstring

object"webhook_endpoint"

urlstringformat: "uri"

enabled_eventslist of strings

statusenum

An endpoint that fails every delivery for 5 days is disabled automatically. Events it missed are not replayed when you enable it again; redeliver them one by one with POST /v1/webhook_events/{webhook_event_id}/redeliver.

Allowed values:

api_versionstring

metadatamap from strings to strings

Up to 50 keys of your own, with keys up to 40 characters and values up to 500 characters.

livemodeboolean

created_atdatetime

descriptionstringOptional

secretstringOptional

The signing secret (whsec_...). Only in create and rotate responses.

last_success_atdatetimeOptional

When the endpoint last acknowledged a delivery.

last_failure_atdatetimeOptional

When a delivery to the endpoint last failed.

failing_sincedatetimeOptional

When the current run of failures began. Left out while deliveries succeed.

disables_atdatetimeOptional

When Runledger will disable the endpoint if it keeps failing, 5 days after failing_since.

actorobjectOptional

Who made a change. Runledger fills it in from the credential, so a client can’t claim to be someone else: an API key always acts as itself, the dashboard calls the API as the signed-in person, and the MCP server passes the client’s name and the person it acts for. A request that sends a Runledger-Actor header is refused with 400 parameter_unknown.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error