Ctrlk
StatusPal.ioBlogStart free
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Outgoing Webhooks

Manage outgoing webhook subscriptions for organization events.

Webhook signing

When an event fires, StatusPal POSTs a JSON payload to your configured outgoing_webhook.url. Every delivery carries the following headers:

Header
Value

Content-Type

application/json

User-Agent

StatusPal-Webhooks/1.0

X-StatusPal-Event

The event name (service.status_changed, notice.created, or notice.updated)

X-StatusPal-Delivery

A per-attempt UUID, use it to dedupe retried deliveries

X-StatusPal-Signature

Stripe-style signature: t=<unix_ts>,v1=<hex_hmac>

The signature covers "#{t}.#{raw_body}", signed with HMAC-SHA256 using the webhook's plaintext signing secret (the whs_… value returned once when the webhook was created or its secret was rotated). Verify it like this:

parsed = parse_header("X-StatusPal-Signature")  # → { t: <int>, v1: <hex> }
signed = `${parsed.t}.${raw_body}`
digest = HMAC_SHA256(secret, signed)
if (Date.now() / 1000 - parsed.t > 300) reject  # 5-minute tolerance recommended
if (!constant_time_eq(digest, parsed.v1)) reject

Delivery retries

Each event is delivered up to 3 times with exponential backoff: 1s, 2s, 4s between attempts. Any 2xx response is treated as success; any other status, a timeout (5s open / 10s read), or a network error triggers the next retry. After the third failure the delivery is dropped.

List outgoing webhooks

get
Authorizations
AuthorizationstringRequired

Organization API key — issue one via the Rails console (management UI coming soon)

Query parameters
pageinteger · min: 1OptionalDefault: 1
per_pageinteger · min: 1 · max: 100OptionalDefault: 20
Responses
200

OK

application/json
get/outgoing_webhooks
GET /api/v1/outgoing_webhooks HTTP/1.1
Host: next.statuspal.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "id": "text",
      "name": "Ops alerts",
      "url": "https://hooks.example.com/statuspal",
      "events": [
        "notice.created",
        "notice.updated"
      ],
      "enabled": true,
      "all_status_pages": true,
      "status_page_subdomains": [
        "prod-status",
        "eu-status"
      ],
      "last_triggered_at": null,
      "last_attempted_at": null,
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 1,
    "total_count": 1,
    "total_pages": 1
  }
}

Create an outgoing webhook

post

Creates a new outgoing webhook. The response includes the plaintext signing secret exactly once — store it immediately, it cannot be retrieved later. Use POST /outgoing_webhooks/{id}/regenerate_secret to rotate.

Authorizations
AuthorizationstringRequired

Organization API key — issue one via the Rails console (management UI coming soon)

Body
namestringRequiredExample: Ops alerts
urlstring · uriRequiredExample: https://hooks.example.com/statuspal
enabledbooleanOptionalDefault: true
all_status_pagesbooleanOptionalDefault: true
status_page_subdomainsstring[]Optional

Required when all_status_pages is false. Subdomains of the status pages this webhook should fire for. Unknown subdomains cause a 422.

Example: ["prod-status","eu-status"]
Responses
201

Created

application/json
post/outgoing_webhooks
POST /api/v1/outgoing_webhooks HTTP/1.1
Host: next.statuspal.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 185

{
  "name": "Ops alerts",
  "url": "https://hooks.example.com/statuspal",
  "events": [
    "notice.created"
  ],
  "enabled": true,
  "all_status_pages": true,
  "status_page_subdomains": [
    "prod-status",
    "eu-status"
  ]
}
{
  "data": {
    "id": "text",
    "name": "Ops alerts",
    "url": "https://hooks.example.com/statuspal",
    "events": [
      "notice.created",
      "notice.updated"
    ],
    "enabled": true,
    "all_status_pages": true,
    "status_page_subdomains": [
      "prod-status",
      "eu-status"
    ],
    "last_triggered_at": null,
    "last_attempted_at": null,
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z",
    "secret": "whs_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  }
}

Get an outgoing webhook

get
Authorizations
AuthorizationstringRequired

Organization API key — issue one via the Rails console (management UI coming soon)

Path parameters
idstringRequired

TypeID-prefixed identifier (e.g. wbk_01h2x...)

Responses
200

OK

application/json
get/outgoing_webhooks/{id}
GET /api/v1/outgoing_webhooks/{id} HTTP/1.1
Host: next.statuspal.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "id": "text",
    "name": "Ops alerts",
    "url": "https://hooks.example.com/statuspal",
    "events": [
      "notice.created",
      "notice.updated"
    ],
    "enabled": true,
    "all_status_pages": true,
    "status_page_subdomains": [
      "prod-status",
      "eu-status"
    ],
    "last_triggered_at": null,
    "last_attempted_at": null,
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z"
  }
}

Delete an outgoing webhook

delete
Authorizations
AuthorizationstringRequired

Organization API key — issue one via the Rails console (management UI coming soon)

Path parameters
idstringRequired

TypeID-prefixed identifier (e.g. wbk_01h2x...)

Responses
204

Deleted

No content
delete/outgoing_webhooks/{id}
DELETE /api/v1/outgoing_webhooks/{id} HTTP/1.1
Host: next.statuspal.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update an outgoing webhook

patch
Authorizations
AuthorizationstringRequired

Organization API key — issue one via the Rails console (management UI coming soon)

Path parameters
idstringRequired

TypeID-prefixed identifier (e.g. wbk_01h2x...)

Body
namestringOptional
urlstring · uriOptional
enabledbooleanOptional
all_status_pagesbooleanOptional
status_page_subdomainsstring[]Optional
Responses
200

OK

application/json
patch/outgoing_webhooks/{id}
PATCH /api/v1/outgoing_webhooks/{id} HTTP/1.1
Host: next.statuspal.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 152

{
  "name": "text",
  "url": "https://example.com",
  "events": [
    "service.status_changed"
  ],
  "enabled": true,
  "all_status_pages": true,
  "status_page_subdomains": [
    "text"
  ]
}
{
  "data": {
    "id": "text",
    "name": "Ops alerts",
    "url": "https://hooks.example.com/statuspal",
    "events": [
      "notice.created",
      "notice.updated"
    ],
    "enabled": true,
    "all_status_pages": true,
    "status_page_subdomains": [
      "prod-status",
      "eu-status"
    ],
    "last_triggered_at": null,
    "last_attempted_at": null,
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z"
  }
}

Rotate the signing secret

post

Replaces the webhook's signing secret with a freshly generated value. The new plaintext secret is returned in this response only — it is not stored in cleartext and cannot be retrieved later.

Authorizations
AuthorizationstringRequired

Organization API key — issue one via the Rails console (management UI coming soon)

Path parameters
idstringRequired

TypeID-prefixed identifier (e.g. wbk_01h2x...)

Responses
200

OK

application/json
post/outgoing_webhooks/{id}/regenerate_secret
POST /api/v1/outgoing_webhooks/{id}/regenerate_secret HTTP/1.1
Host: next.statuspal.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "id": "text",
    "name": "Ops alerts",
    "url": "https://hooks.example.com/statuspal",
    "events": [
      "notice.created",
      "notice.updated"
    ],
    "enabled": true,
    "all_status_pages": true,
    "status_page_subdomains": [
      "prod-status",
      "eu-status"
    ],
    "last_triggered_at": null,
    "last_attempted_at": null,
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z",
    "secret": "whs_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  }
}
PreviousNotice Updates
NextWebhook Events

Last updated