Documentation menu

Connect

Webhooks

How to receive Project and Environment events in your own systems.

A webhook subscription tells Perstack to push domain events to a URL you control as they happen. Use it when your own systems need to react to a Project or Environment change without polling. A subscription is created under an explicit Project Environment scope; it does not receive events from another Project.

Setting one up

Creating a subscription takes an HTTPS endpoint URL and the event types it should receive. It is created under an explicit Project Environment scope and does not receive events from another Project or Environment. The subscription metadata reports its lifecycle mode as live, paused, or deleting; these are persisted states, not selectable delivery modes in the create request.

An installation restricted to private Webhook destinations accepts outbound subscriptions only when delivery is explicitly enabled and the destination is in its installation-owned private HTTPS policy. The policy constrains the origin, port and every resolved address against approved private CIDRs; subscription settings cannot override it. When delivery is disabled or the destination is unavailable, creating or re-enabling a subscription returns 409 Conflict with details.conflictReason outbound_webhooks_unsupported and changes nothing. Listing, reading, pausing and deleting remain available. Ask the installation operator to confirm an existing approved destination; creating a subscription does not grant network access. SaaS delivery keeps its public HTTPS/SSRF policy.

The response to creating a subscription includes a signing secret. It is shown exactly once — store it. The same one-time secret rule applies when you create a replacement secret for an existing webhook. See Signed delivery below.

Full request and response shapes are in the API reference.

Webhook operations use the authenticated principal's grants. Listing and reading require webhooks:list; creation and update require webhooks:create; removal requires webhooks:delete; secret rotation requires webhooks:rotate-secret; dead-letter retry requires webhooks:retry-dead; and retained-delivery replay requires webhooks:replay. A grant does not bypass the explicit Organization, Project, and Environment scope of the request.

Signed delivery

Deliveries follow the Standard Webhooks specification, so any published Standard Webhooks library verifies them with the signing secret as issued (whsec_ followed by a base64 key). The body is the canonical event. Each request carries three headers:

  • webhook-id: the event id. It stays the same across retries and replays of the event, so use it to deduplicate.
  • webhook-timestamp: the attempt time in Unix seconds. Reject values far from your clock to refuse replayed requests.
  • webhook-signature: v1, followed by the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body} over the exact raw body, keyed with the base64-decoded part of the secret after whsec_.

A webhook created before signing followed Standard Webhooks has a secret without the whsec_ prefix, which these libraries reject. Rotate its signing secret once to receive a whsec_ secret.

If a signing secret is compromised, or you simply want to rotate it, rotate the secret on the existing subscription. The replacement is returned once and is not shown again. Once the rotation commits, every later delivery attempt is signed with the new secret, including retries and replays of earlier events. For 24 hours after the rotation, each attempt also carries a signature under the previous secret in the same webhook-signature header, separated by a space, so you can switch your endpoint to the new secret at any point in that day. An attempt already claimed when the rotation committed carries the previous secret only. To revoke a leaked secret, rotate it and drop the previous secret from your endpoint at once: every later attempt verifies with the new one.

Retries and recovery

Any HTTP non-2xx response is retryable and redirects are never followed. A failed attempt is retried after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours and 10 hours; a longer valid Retry-After is honored up to one hour. A receiver has 15 seconds to answer. Invalid URL, non-HTTPS, blocked/private-host, and address-validation policy failures are permanent. After seven attempts or the 24-hour delivery bound, the persisted delivery status is dead_letter and the Organization's owners and admins are emailed with the delivery's expiry time, at most 24 hours after its creation. Before that time, retry-dead resets an eligible exact delivery to pending without rewriting event history; after it, the delivery is never sent again. An ineligible delivery returns 409 Conflict. Delivered deliveries and dead letters stay listed as long as their event, 30 days; a delivery still unfinished at its expiry time is removed then.

Replaying a delivery before its expiry time is different from retrying it. A replay creates a new durable delivery request for the same original event identity while preserving the original delivery's outcome and attempt history. It does not turn an active or completed delivery into a retry, and it requires an Idempotency-Key header containing no spaces and only printable ASCII characters (! through ~), 1–64 characters. Reuse the same key for a network retry; a changed request or an in-progress or mismatched claim is a 409 Conflict and must not be treated as a new delivery.

Because retries and replays can result in the same event being delivered more than once, an endpoint that acts on events should treat delivery as at-least-once and be able to handle receiving the same event twice. Replays are limited to deliveries before their expiry time; an unavailable parent, delivery, or cross-scope resource is not enumerated as an empty success.

See the API reference for the specific operations these recovery paths correspond to.

Related