Register a new webhook for the authenticated brand.

POST

/brands/me/webhooks

• Production
• Staging
• Local dev

Returns the webhook DTO with a one-time raw secret. The server stores only the AES-encrypted form; the raw secret is NEVER shown again. Supported events: polst.voted, polst.closed, campaign.step_completed, campaign.completed, brand.updated, brand.theme_updated.

Authorizations

• bearerAuth

Parameters

Header Parameters

X-Polst-Idempotency-Key

required

string

>= 8 characters <= 255 characters

Idempotency key, 8–255 URL-safe chars.

Request Body ^required

object

url

required

string format: uri

<= 2048 characters

description

Any of:

string

string

<= 255 characters

null

null

events

required

Array<string>

>= 1 items

Allowed values: polst.voted polst.closed campaign.step_completed campaign.completed brand.updated brand.theme_updated

Responses

201

Webhook created.

object

data

required

object

id

required

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

url

required

string format: uri

description

required

Any of:

string

string

null

null

events

required

Array<string>

Allowed values: polst.voted polst.closed campaign.step_completed campaign.completed brand.updated brand.theme_updated

status

required

string

Allowed values: ACTIVE DISABLED

createdAt

required

string format: date-time

/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/

updatedAt

required

string format: date-time

/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/

secret

required

string

>= 32 characters

400

Missing idempotency key.

401

Missing or invalid bearer token.

403

Bearer token lacks manage scope or brand context.

422

Request body failed validation.