Webhooks API

Lists the project's webhook notifications in the webhook shape, oldest first (at most 50); GET /api/notifications lists every channel. The signing secret is never returned here. Requires the project capability; a reports-only credential is refused 403 forbidden, because the response includes receiver URLs.

Creates a webhook that receives the project's own durable events as signed HTTPS POSTs. url must be https on a public Internet host: an IP literal or every current DNS answer of the name must be public (private, loopback, link-local, CGNAT, IPv6 outside 2000::/3, documentation, and other reserved ranges are refused with webhook_url_rejected).

The port must be 443 (the default) or 8443, else webhook_url_rejected. The host is resolved and checked again before every delivery and the connection is dialed to exactly the checked address, so a DNS answer that changes later cannot redirect deliveries. event_types lists exact event types (screen.online) or prefixes ending in .* (screen.*).

An organization has at most 50 notifications across every channel (webhook_limit_reached). The server generates the signing secret and returns it only in this answer and in rotate-secret; store it. An exact retry with the same Idempotency-Key returns this same answer, secret included, for twenty-four hours.

Delivery starts with the first event after notification.created.

Requires the project capability; a reports-only credential is refused 403 forbidden, because the response includes receiver URLs.

Changes any of url, event_types, enabled, and description (an empty description clears it). A new url is checked like create.

Setting enabled true on a disabled webhook clears its failure state and starts delivery at the event that records the change; events from while it was disabled are not replayed, and deliveries still pending from before the disable are failed with webhook_disabled. Setting enabled false fails its pending deliveries with webhook_disabled.

Appends notification.updated. If-Match guards the revision.

Deletes the webhook and appends notification.deleted. Its pending deliveries are failed with webhook_deleted; its delivery log is no longer addressable and expires with event retention.

Replaces the signing secret and returns the new one; the old secret stops signing at once: every attempt that signs after this commits uses the new secret, and at most one attempt per webhook already in flight may still arrive signed with the old one, so accept both briefly. Appends notification.updated with details.changed [secret].

An exact retry with the same Idempotency-Key returns the same new secret for twenty-four hours.

Appends a notification.test project event and queues one delivery of it to this webhook only (no other webhook receives notification.test). It works on a disabled webhook, is attempted once without retries, is metered like any delivery, and never changes the webhook's failure state. Poll the deliveries log for its outcome.

The webhook's delivery log, newest event first. One row per (webhook, event); retries update the row and GET .../deliveries/{delivery_id}/attempts lists its most recent attempts. Rows are retained like events (the plan's event retention, at least the 24-hour retry window). Pass next_cursor back as before for the next page.

One delivery's attempts, newest first, the most recent 20, kept with the delivery row and for as long. Each has its attempt number, when it finished, the receiver's HTTP status (null when none answered), the error class (null on success) and its duration. Response bodies and headers are never kept. A delivery recorded before attempts were kept lists none.

A delivery that is not this webhook's, or a webhook of another project, is not_found.