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

/outgoing_webhooks

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

application/json

401

Missing or invalid API key

application/json

403

The account is pending activation. A newly created account must be activated by an administrator before its API key can be used.

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": "2026-07-16T01:39:46.281Z",
      "last_attempted_at": "2026-07-16T01:39:46.281Z",
      "created_at": "2026-07-16T01:39:46.281Z",
      "updated_at": "2026-07-16T01:39:46.281Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 1,
    "total_count": 1,
    "total_pages": 1
  }
}

Create an outgoing webhook

post

/outgoing_webhooks

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

401

Missing or invalid API key

application/json

403

The account is pending activation. A newly created account must be activated by an administrator before its API key can be used.

application/json

422

Validation failed

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": "2026-07-16T01:39:46.281Z",
    "last_attempted_at": "2026-07-16T01:39:46.281Z",
    "created_at": "2026-07-16T01:39:46.281Z",
    "updated_at": "2026-07-16T01:39:46.281Z",
    "secret": "whs_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  }
}

Get an outgoing webhook

get

/outgoing_webhooks/{id}

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

application/json

401

Missing or invalid API key

application/json

403

The account is pending activation. A newly created account must be activated by an administrator before its API key can be used.

application/json

404

Resource not found

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": "2026-07-16T01:39:46.281Z",
    "last_attempted_at": "2026-07-16T01:39:46.281Z",
    "created_at": "2026-07-16T01:39:46.281Z",
    "updated_at": "2026-07-16T01:39:46.281Z"
  }
}

Delete an outgoing webhook

delete

/outgoing_webhooks/{id}

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

401

Missing or invalid API key

application/json

403

The account is pending activation. A newly created account must be activated by an administrator before its API key can be used.

application/json

404

Resource not found

application/json

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

/outgoing_webhooks/{id}

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

application/json

401

Missing or invalid API key

application/json

403

The account is pending activation. A newly created account must be activated by an administrator before its API key can be used.

application/json

404

Resource not found

application/json

422

Validation failed

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": "2026-07-16T01:39:46.281Z",
    "last_attempted_at": "2026-07-16T01:39:46.281Z",
    "created_at": "2026-07-16T01:39:46.281Z",
    "updated_at": "2026-07-16T01:39:46.281Z"
  }
}

Rotate the signing secret

post

/outgoing_webhooks/{id}/regenerate_secret

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

application/json

401

Missing or invalid API key

application/json

403

The account is pending activation. A newly created account must be activated by an administrator before its API key can be used.

application/json

404

Resource not found

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": "2026-07-16T01:39:46.281Z",
    "last_attempted_at": "2026-07-16T01:39:46.281Z",
    "created_at": "2026-07-16T01:39:46.281Z",
    "updated_at": "2026-07-16T01:39:46.281Z",
    "secret": "whs_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  }
}

PreviousNotice Updates NextWebhook Events

Last updated 1 month ago