Skip to main content

Webhooks

Webhooks let Slothbox push events to your own server the moment something happens in your organization — an environment starts or stops, a member joins, billing changes, and more. Instead of polling the API, you register an HTTPS endpoint and Slothbox delivers a signed POST to it for every event you subscribe to.

Webhooks are org-scoped and owner-managed: each endpoint belongs to one organization, and only org owners can create, edit, or delete them.

Managing endpoints​

You can manage endpoints from the web app or the API.

  • Web app — open Settings → Webhooks to add an endpoint, choose which events it receives, send a test delivery, browse the delivery log, replay a past delivery, and rotate the signing secret.
  • API — the same operations are available under /organizations/{orgId}/webhooks (owner-only). See the API reference for every route and schema.

Creating an endpoint over the API looks like this:

curl https://api.slothbox.dev/organizations/org_123/webhooks \
  -H "Authorization: sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/slothbox",
    "eventTypes": ["environment.started", "environment.stopped"],
    "description": "Prod notifier",
    "ordered": false
  }'

url and a non-empty eventTypes are required; description (≤200 chars, a label for your own reference) and ordered (see ordered delivery) are optional.

The response contains the new endpoint and its signing secret (other fields elided for brevity — the full schema is in the API reference):

{
  "endpoint": {
    "endpointId": "whe_01HXYZ",
    "url": "https://example.com/webhooks/slothbox",
    "eventTypes": ["environment.started", "environment.stopped"],
    "status": "enabled",
    "ordered": false,
    "consecutiveFailures": 0,
    "createdAt": "2026-05-30T14:23:00.000Z",
    "updatedAt": "2026-05-30T14:23:00.000Z"
  },
  "secret": "whsec_..."
}
warning

The secret is shown once, at creation. Store it somewhere safe — you'll need it to verify deliveries. If you lose it, you can roll the secret to get a new one.

To pause an endpoint without deleting it, PATCH its status to disabled (and back to enabled to resume) — useful while you debug your receiver.

Choosing events​

Each endpoint subscribes to a list of event types. You can list specific types, or subscribe to all events with * (which also delivers any types we add later):

{ "url": "https://example.com/webhooks/slothbox", "eventTypes": ["*"] }

The full catalogue is available at runtime from GET /organizations/{orgId}/webhooks/event-types. To change an endpoint's subscription later, PATCH it with the full eventTypes list you want — the update replaces the list rather than merging, so include every type you want to keep.

Send a test event​

Once an endpoint exists, fire a webhook.ping at it to confirm your receiver works end-to-end — from Settings → Webhooks, or over the API:

curl -X POST \
  https://api.slothbox.dev/organizations/org_123/webhooks/whe_01HXYZ/ping \
  -H "Authorization: sk_..."

The response is the queued delivery's id:

{ "webhookId": "msg_01HXYZ" }

Your endpoint then receives a webhook.ping delivery you can verify exactly like any real event.

Next steps​

  • Receiving & verifying — the request shape and how to verify a delivery is genuinely from Slothbox.
  • Events — the full event catalogue and payloads.
  • Delivery & retries — retries, auto-disable, replay, secret rotation, and ordered delivery.