Skip to navigation
API ReferenceWebhooksEvent payload

Runledger event

Runledger posts a thin event to each enabled endpoint subscribed to its type. The body names the event type and the object it is about; fetch the object for its current state before acting. Deliveries follow Standard Webhooks: webhook-id (constant across retries, so use it to deduplicate), webhook-timestamp and webhook-signature (HMAC-SHA256, v1, prefix). Events arrive at least once and in no guaranteed order. Failed deliveries are retried with exponential backoff for 3 days. Respond with any 2xx within 15 seconds.

Headers

webhook-idstringRequired
Unique per event. The same on every retry.
webhook-timestampstringRequired
Unix seconds when this attempt was signed. Reject attempts older than 5 minutes.
webhook-signaturestringRequired

Space-separated v1,<base64 HMAC-SHA256> signatures over webhook-id.webhook-timestamp.body. Two are present while a secret rotates.

Payload

The payload of this webhook request is an object.
idstringRequired
object"webhook_event"Required
typeenumRequired
New types may be added. Subscribe only to the ones you handle.
api_versionstringRequired
related_objectobjectRequired
livemodebooleanRequired
created_atdatetimeRequired
reasonobjectOptional
What caused the event.
contextobjectOptional

The fields that identify what a limit, window or purchase event is about, for events that don’t name a stored object of their own. Fetch related_object for the current state.

delivery_statusenumOptional

pending: still being sent or retried. succeeded: every subscribed endpoint acknowledged it. failed: retries ran out for at least one endpoint.

Allowed values:
deliverieslist of objectsOptional
Retrieve only. The last 10 attempts per endpoint.

Response

200
Any 2xx status acknowledges the event.
400

The request was malformed or a parameter was invalid. A configuration that fails validation, such as two equally specific overrides with overlapping dates, returns config_invalid.

403

The key can’t do this. A restricted or agent key lacks the scope (insufficient_scope, with required_scope), a live key called a sandbox-only endpoint, an agent tried a live config write that needs a proposal (proposal_required), or something only a signed-in person can do.