Create webhook endpoint

POSThttps://app.speybooks.com/api/v1/webhooks/

Register a new webhook endpoint. A cryptographically secure signing secret is generated automatically and returned in this response ONLY. It cannot be retrieved again: store it securely for payload verification now. If it is ever lost, rotate it.

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

Body parameters

eventsarray<string>required

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

urlstringrequired

HTTPS URL to receive webhook deliveries (max 2048 characters). Plain HTTP is rejected.

descriptionstringoptional

Optional description for the endpoint (max 255 characters).

Response

201Webhook endpoint created. The signing secret is returned ONCE in this response and cannot be retrieved again; store it now. Recovery is rotation.

Show response fields

eventsarray<string>

idinteger

isActiveboolean

secretstring

urlstring

Error codes

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

409Maximum 5 webhook endpoints per organisation reached.

RequestPOST/v1/webhooks/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"]}'

Response201

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