Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.envless.cloud/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks let your services react to changes in an Envless workspace the moment they happen — a new project, a rotated key, a removed member, a failed delivery — without polling the API.

​
How it works

  1. You configure one or more webhook endpoints per workspace (URL + selected event types + signing secret).
  2. When a matching mutation succeeds, Envless writes a WorkspaceEvent row in the same database transaction as the mutation, then creates one WebhookDelivery per endpoint that subscribes to that event type.
  3. A background worker picks up pending deliveries, signs each request with the endpoint’s secret, and POSTs the payload to your URL.
  4. Failed deliveries retry on exponential backoff. After the final retry, the delivery is marked failed and (if subscribed) a webhook.delivery_failed meta-event is fanned out.

​
Delivery guarantees

  • At-least-once. A receiver may see the same event more than once; verify the webhook-id header and dedupe.
  • Order is not guaranteed. Deliveries are processed in parallel and may arrive out of order.
  • Per-endpoint isolation. Each endpoint signs with its own secret; a compromised receiver can’t impersonate another.

​
Retry policy

AttemptDelay before retry
1st failure30 s
2nd2 min
3rd10 min
4th30 min
5th1 h
After 5 unsuccessful attempts the delivery is marked failed and no further attempts are made. The endpoint’s consecutiveFailures counter is incremented on each failure and reset to 0 on the next successful delivery.

​
Request shape

POST https://your-receiver.example.com/webhooks
Content-Type: application/json
User-Agent: Envless-Webhooks/1.0
Envless-Event: project.created
Envless-Delivery: 019e7d98-6b82-7305-ac80-478fa6557995
webhook-id: <event uuid>
webhook-timestamp: <unix seconds>
webhook-signature: v1,<base64 hmac>

{
  "id": "019e7d98-6b82-7305-ac80-478fa6557995",
  "type": "project.created",
  "apiVersion": "2026-05-31",
  "createdAt": "2026-05-31T10:33:20.123Z",
  "workspaceId": "...",
  "actor": {
    "userId": "...",
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "data": {
    "project": {
      "id": "...",
      "name": "billing-service",
      "slug": "billing-service",
      "icon": null,
      "createdAt": "2026-05-31T10:33:20.123Z"
    }
  }
}
The actor is null for system-driven events (e.g. subscription.* driven by Polar webhooks).

​
Security

  • Always verify the signature before processing — see Signature Verification.
  • Treat the secret like a password: store in your secret manager, never commit to git, rotate if leaked.
  • Endpoint URLs must be http(s). We recommend https everywhere except local development.