Create webhook endpoint

POST https://app.speybooks.com/api/v1/webhook-endpoints/

Register a new webhook endpoint. A cryptographically secure signing secret is generated automatically and returned in the response. Store it securely for payload verification.

Enforces a maximum of 5 endpoints per organisation. At least one event must be subscribed.

Body parameters

events array<string> required

Event types to subscribe to. At least one required. See GET /webhooks for available events.

url string required

HTTPS URL to receive webhook deliveries (max 2048 characters).

description string optional

Optional description for the endpoint (max 255 characters).

Response

201 Webhook endpoint created. Returns endpoint details including the signing secret.

Show response fields

events array<string>

id integer

isActive boolean

secret string

url string

Error codes

400 Validation error: invalid URL, missing events, or invalid event types.

409 Maximum 5 webhook endpoints per organisation reached.

Request POST /v1/webhook-endpoints/ curl

curl -X POST https://api.speybooks.com/v1/webhooks \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhooks", "events": ["invoice.paid", "payment.received"]}'

Response 201

{
  "success": true,
  "data": {
    "id": 4,
    "url": "https://example.com/webhooks",
    "secret": "whsec_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1g0",
    "events": [
      "invoice.paid",
      "payment.received"
    ],
    "isActive": true
  }
}