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 afterwhsec_.
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.