Create subscription (raw secret returned ONCE)

Overview

Create an outbound webhook subscription for the caller's partner. The server generates a 256-bit HMAC secret and returns the raw value ONCE in hmac_secret (never recoverable afterward except via reveal/rotate). Each partner may hold at most one non-deleted subscription per delivery_kind slot (one immediate + one batch).

Prerequisites

A bearer token. Callable with Partner tokens.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

POST /api/v1/partner/webhooks

Authentication

Requires a bearer token in the Authorization: Bearer <bearer-token> header.
Who can call it: Partner tokens.
requirePartnerCompanyId enforces bundle_id === 1 (403 otherwise).
partner_company_id is taken from the auth user, not the body.

Rate limit

No rate limit.

Request body

Body:

Field	Type	Required	Description
`label`	string	yes	max 255
`webhook_url`	string (url)	yes	`url:http,https`, max 2048
`delivery_kind`	string	yes	`immediate` \| `batch`; unique-slot rule — fails 422 if a non-deleted sub of the same kind already exists for this partner
`batch_interval_hours`	int\|null	required if `delivery_kind=batch`	one of `[1,2,4,6,12]`; nullable/ignored for immediate
`events`	array\|null	no	omit or `[]` = all events (persisted as null). Batch subs ignore it (pinned null). On immediate slot, batch-kind events are rejected; hipages-only events rejected for non-hipages partners
`events.*`	string	—	Must be one of the event names from the events catalog (`GET /api/v1/partner/webhooks/events`).
`payload_mode`	string	no	`full` \| `minimal`; defaults `full`; forced `full` on batch subs
`is_active`	bool	no	defaults `true`

{
  "label": "Production webhook",
  "webhook_url": "https://partner.example.com/hooks/sau",
  "delivery_kind": "immediate",
  "is_active": true,
  "events": [
    "review_pull_connected",
    "review_pull_disconnected",
    "usage.limit_reached"
  ],
  "payload_mode": "full"
}

Response

data.hmac_secret (string) — raw secret, shown ONCE
data.hmac_secret_warning (string) — store-it-now warning
(no events filter persisted for batch subs → events: null; payload_mode forced full; last_batch_dispatched_at set to creation time for batch, null for immediate)

201 Created · `201`

{
  "data": {
    "data": {
      "id": 2,
      "partner_company_id": 5,
      "label": "Production webhook",
      "webhook_url": "https://partner.example.com/hooks/sau",
      "events": [
        "review_pull_connected",
        "review_pull_disconnected",
        "usage.limit_reached"
      ],
      "payload_mode": "full",
      "delivery_kind": "immediate",
      "batch_interval_hours": null,
      "delivery_label": "immediate",
      "last_batch_dispatched_at": null,
      "is_active": true,
      "hmac_secret_fingerprint": "587647e874083b23",
      "last_succeeded_at": null,
      "last_failed_at": null,
      "last_failure_reason": null,
      "consecutive_failure_count": 0,
      "created_at": "2026-06-16T10:23:23+00:00",
      "updated_at": "2026-06-16T10:23:23+00:00",
      "hmac_secret": "whsec_DUMMYsecretFORdocsONLYdoNOTuse00000000",
      "hmac_secret_warning": "Store this value securely — it will not be shown again. Use it to verify the X-SAU-Signature header on every incoming delivery."
    }
  }
}

Errors

Status	Meaning
`401`	The bearer token is missing, expired or invalid
`422`	Returned if a non-deleted sub of the same kind already exists for this partner
`500`	Unexpected server error

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/partner/webhooks" \
  --header 'Authorization: Bearer {{bearerToken}}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"label": "Production webhook", "webhook_url": "https://partner.example.com/hooks/sau", "delivery_kind": "immediate", "is_active": true, "events": ["review_pull_connected", "review_pull_disconnected", "usage.limit_reached"], "payload_mode": "full"}'

Updated 8 days ago

Did this page help you?