Webhook Endpoints

Register a webhook endpoint

curl -X POST https://api.subscriby.net/v1/webhook-endpoints \
  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Zapier trigger",
    "url": "https://hooks.zapier.com/hooks/catch/...",
    "events": ["subscription.created", "payment.succeeded"]
  }'

Answers 201 with the endpoint and, at the top level beside data, the plaintext signing secret.

The secret appears once. The plaintext secret (prefixed whsec_) appears at the top level of the response only here and on rotate-secret. Subsequent reads never surface it; copy it into your consumer's secret storage immediately.

post/v1/webhook-endpoints

Request

  • Base URL: https://api.subscriby.net
  • URL: https://api.subscriby.net/v1/webhook-endpoints
  • Auth: HTTP bearer

Headers

Idempotency-Keystring uuid required

A key unique to this operation, such as a fresh UUID. The same key replays the original 2xx response for 24 hours (with Idempotent-Replay: true), so a retry after a timeout never repeats the write; the same key with a different body is refused with 409.

Request body

namestring required

A label for the endpoint, 3 to 100 characters.

urlstring uri required

The target, https:// only, up to 2,048 characters, pointing at a public host: loopback, private, link-local and reserved addresses are refused, as is a public hostname that resolves to one.

project_idstring uuid nullable

Confine the endpoint to one project's events; omit it for a team-wide subscription.

eventsstring[] required

The events to subscribe to, at least one.

allowed_ipsstring[] nullable

IPv4/IPv6 addresses or CIDR ranges the target must resolve to. Enforced on every delivery: when the endpoint's host resolves to an address outside the list, the delivery is dead-lettered without being posted.

is_activeboolean

Whether deliveries flow from the start. Defaults to true.

Response

201 with the resource and a top-level secret.

secretstring required

The plaintext signing secret, whsec_…, returned once. Verify every delivery's SB-Signature with it.

Example response

{
  "data": {
    "id": "c62a08f4-1b7d-4e35-9860-a37f5d21e0b9",
    "name": "Zapier trigger",
    "url": "https://hooks.zapier.com/hooks/catch/...",
    "events": [
      "subscription.created"
    ],
    "is_active": true,
    "created_at": "2026-05-18T10:05:00Z",
    "updated_at": "2026-05-18T10:05:00Z"
  },
  "secret": "whsec_a1b2c3..."
}

Changes

No recorded changes to this operation across all 1 revision of this API.