Create a webhook subscription

POST

/event-subscriptions

curl --request POST \
  --url https://app.surveyrock.com/api/v1/event-subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "url": "example", "event_types": [ "response.completed" ] }'

• API v1 endpoints

Registers a URL that SurveyRock sends the chosen events to, signed and retried (see the webhooks guide for the signature scheme and the retry schedule). Omit url to create an event feed: nothing is sent, and the workspace’s events are recorded for GET /events.

The response contains the signing secret (secret, starting whsec_). It is shown once: store it now. Lose it and you replace it with rotate-secret. This request is not covered by Idempotency-Key, because that would store the secret; a retry of a create whose response you lost is a 409 duplicate_subscription.

Needs the events:write scope, which a token has to ask for by name (the * wildcard does not include it). The workspace’s owners and admins are emailed when a subscription is created.

Authorizations

• bearerAuth
  events:write

Request Body^required

Media typeapplication/json

object

name

required

A label for you

string

<= 100 characters

url

An https URL we may deliver to: no credentials in it, and it must resolve to a public address. Omit or null for an event feed

string

nullable <= 2048 characters

event_types

Default: all of them

Array<string>

Allowed values: response.completed

Responses

201

Created. Location is the new subscription. data.secret is the signing secret, shown once (absent for an event feed).

403

The plan does not include webhooks (feature_locked), or the token lacks events:write

409

duplicate_subscription (the workspace already has one for that URL) or subscription_limit_reached (20 per workspace)

422

validation_failed: each error names the field