List webhook subscriptions

GET

/v1/webhook-subscriptions

const url = 'https://api.aerandil.com/v1/webhook-subscriptions';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.aerandil.com/v1/webhook-subscriptions \
  --header 'Authorization: Bearer <token>'

Returns every subscription owned by the calling tenant. Tenant scoping is automatic — a token issued for tenant A cannot enumerate tenant B’s subscriptions.

The signing_key is never echoed by list/get — only the primary_key_fingerprint (and secondary_key_fingerprint during rotation).

Authorizations

aerandil_oauth
webhooks:read

Responses

200

Subscriptions for the calling tenant.

application/json

object

data

required

Array<object>

Subscription state without the signing key. The *_key_fingerprint fields are the first 8 hex chars of sha256(key) — enough to confirm a rotation worked without exposing the secret.

object

consecutive_failures

required

Resets to 0 on the first 2xx after any failure. Transitioning to dead_letter happens at 12 consecutive failures (~3-day retry window).

integer

created_at

required

string format: date-time

filter

required

Filter narrowing what the worker delivers. Empty / absent means “every event in the tenant”.

object

object_types

Narrow to events whose object_type matches one of the listed api_names. For link events, either endpoint type matching counts — a filter of ["hospitality.reservation"] includes reservation_for_guest events.

Array<string>

required

string format: uuid

last_delivered_seq

required

Cursor into the event log. Advances to the highest seq read on every successful delivery — filtered-out events are still cursored past so the worker stays bounded under a narrow filter.

integer

next_attempt_at

Earliest moment the worker will retry. Unset when the subscription is caught up; set in the future when an exponential-backoff retry is scheduled.

string format: date-time

primary_key_fingerprint

required

First 8 hex chars of sha256(primary_signing_key) — 16 chars in total. Exposed instead of the secret on every read.

string

/^[0-9a-f]{16}$/

secondary_key_fingerprint

Present during a key-rotation window. Cleared on promote-key.

string

/^[0-9a-f]{16}$/

status

required

Lifecycle of a webhook subscription. dead_letter is sticky — the worker stops attempting further deliveries until the customer PATCHes status back to active (and typically advances last_delivered_seq past the poison batch).

Allowed values: active paused dead_letter

tenant_id

required

string format: uuid

updated_at

required

string format: date-time

url

required

Receiver URL. HTTPS-only (except loopback in dev).

string format: uri

Example

{
  "data": [
    {
      "status": "active"
    }
  ]
}