Webhooks — API reference

Registering and testing delivery endpoints.

Generated from openapi.yaml at build time. Base URL https://api.tenergy.me/v1, or https://api-nile.tenergy.me/v1 on Nile (Environments). Every request below is signed as in Authentication unless its Auth line says otherwise.

List delivery endpoints

GET /v1/webhooks · listWebhooks

Auth: API key (HMAC).

The secret is never returned here.

Responses

Response fields

Register a delivery endpoint

POST /v1/webhooks · createWebhook

Auth: API key (HMAC).

Returns a secret shown exactly once. It signs every delivery to this endpoint — store it now; if you lose it, rotate rather than re-register.

At most two endpoints per account: one primary and one backup. Delivery is not fan-out — every event goes to the primary, and moves to the backup only after the primary’s retries are exhausted. The first endpoint you create becomes primary.

URL requirements, enforced on create and on every edit: https only; must resolve to a public address (loopback, RFC 1918, link-local including 169.254.169.254 and other non-routable ranges are rejected); no credentials in the URL; at most 2048 characters.

Full event catalogue, payloads, signature scheme and retry schedule: Webhooks.

Request body

JSON (WebhookRequest), required.

Example request body, from the contract (illustrative values):

{
  "url": "https://acme.example/hooks/tenergy",
  "role": "primary",
  "events": ["order.confirmed","order.failed","balance.credited"]
}

Responses

Response fields

Read one endpoint

GET /v1/webhooks/{webhookId} · getWebhook

Auth: API key (HMAC).

Parameters

Responses

Response fields (WebhookEndpoint)

Edit an endpoint

PATCH /v1/webhooks/{webhookId} · updateWebhook

Auth: API key (HMAC).

Change url, events, is_active and/or role. Sending {"role": "primary"} to the backup swaps the two roles in one transaction, so you are never left without a primary. A changed URL is re-validated. is_active: false pauses delivery without losing the endpoint; pausing the primary does not promote the backup — swap the roles if that is what you want.

Parameters

Request body

JSON (WebhookPatch), required.

Responses

Response fields (WebhookEndpoint)

Delete an endpoint

DELETE /v1/webhooks/{webhookId} · deleteWebhook

Auth: API key (HMAC).

Hard delete; frees the role. Undelivered events for this endpoint are dropped.

Parameters

Responses

Issue a new signing secret

POST /v1/webhooks/{webhookId}/rotate-secret · rotateWebhookSecret

Auth: API key (HMAC).

Returns a new secret once. It takes effect immediately for subsequent deliveries; there is no overlap window, so deploy the new secret to your receiver before rotating, or accept a brief period where in-flight retries fail signature verification. Each endpoint has its own secret — rotating the primary’s does not touch the backup’s.

Parameters

Responses

Response fields

Send a test delivery

POST /v1/webhooks/{webhookId}/test · testWebhook

Auth: API key (HMAC).

Sends a synthetic event to the endpoint and reports what your server answered. The payload is signed exactly like a real one and carries "test": true at the top level, so a receiver that ignores unknown event types, or that checks the flag, will not act on it.

Test deliveries are not retried and do not appear in delivery history.

Parameters

Request body

JSON.

Responses

Response fields

Delivery log of one endpoint

GET /v1/webhooks/{webhookId}/deliveries · listWebhookDeliveries

Auth: API key (HMAC).

Every event queued for this endpoint, newest first: which event, how many attempts, the state, the last HTTP status your server answered and when the next retry is due. Test deliveries are not listed. Scope webhooks.read, or a dashboard session with member role viewer. Another account’s endpoint answers 404.

Parameters

Responses

Response fields

Example 200 response, from the contract (illustrative values — live numbers come from the API):

{
  "data": [
    {
      "id": "dlv_01K5YA1B2C3D4E5F6G7H8J9K0M",
      "event_id": "evt_01K5YA1B2C3D4E5F6G7H8J9K0N",
      "event": "order.confirmed",
      "attempt": 2,
      "state": "failed",
      "response_status": 502,
      "error": null,
      "next_attempt_at": "2026-09-25T10:31:00.000Z",
      "delivered_at": null,
      "created_at": "2026-09-25T10:30:00.000Z",
      "updated_at": "2026-09-25T10:30:30.000Z"
    }
  ],
  "next_cursor": null
}