Webhooks

Register an endpoint

POST/v1/webhooks

Registers a webhook endpoint. The signing secret is returned once.

API key · or dashboard session.

Request

Shell
curl -fsS "$API/v1/webhooks" \
  -H "Authorization: Bearer $PAYDAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/payday/webhook" }'

Response

201 Created
{
  "id": "wh_0198f80c-3333-7dc1-a369-90556a64f700",
  "url": "https://example.com/payday/webhook",
  "secret": "whsec_…",
  "created_at": "2026-09-06T12:00:00Z",
  "disabled_at": null
}

HTTPS; DNS hostname; no credentials. Private, loopback, link-local, and reserved destinations are rejected at registration and before each delivery. Redirects are not followed. Event types, payloads, signatures, retry policy: Webhooks.

Body

urlstringrequired

Response

Webhook with secret. This response only.

Status codes

  • 400invalid_request URL rejected. Message states why.
  • 503webhooks_unavailable No encryption key configured.