create

POST /api/v1/accounts/:account_id/webhook_subscriptions

Create a webhook subscription

Subscribes a URL to one or more events. The response includes the signing secret; store it to verify deliveries. The URL must be publicly reachable over https.

Events: customer.created, customer.updated, customer_card.created, stamp.earned, stamp.removed, reward.unlocked, reward.redeemed, or ‘*` for all of them.

Parameters

Name	Type	Required	Description
`account_id`	Must be a number.	Required	Store (account) ID
`events`	Must be an array of String	Optional	Events to subscribe to, or ‘[“*”]` for every event. Required unless `event` is given
`event`	Must be a String	Optional	A single event to subscribe to. Same as `events` with one entry
`target_url`	Must be a String	Required	Public https URL that will receive the POST requests
`description`	Must be a String	Optional	Your own label, up to 255 characters
`payload_format`	Must be a String	Optional	`envelope` (default) or `flat`. `flat` sends the bare data object and cannot be combined with ‘*`
`enabled`	Must be one of: `true`, `false`, `1`, `0`.	Optional	Create the subscription disabled by passing false (defaults to true)

Error Codes

Code	Description
`401`	Unauthorized – invalid or missing API token
`404`	Store not found
`422`	Validation failed – check `errors` for details

Returns

Code: 201

The new webhook subscription, with its secret

Name	Type	Required	Description
`id`	Must be a Integer	Required	Unique subscription ID
`account_id`	Must be a Integer	Required	Parent store ID
`events`	Must be an array of String	Required	Events delivered to this URL, or ‘[“*”]` for every event
`event`	Must be a String	Required	The event, when there is exactly one (kept for older integrations) (nil allowed)
`target_url`	Must be a String	Required	URL that receives the POST requests
`description`	Must be a String	Required	Your own label for the subscription (nil allowed)
`payload_format`	Must be a String	Required	`envelope` (default) or `flat` (the bare data object, used by Zapier)
`enabled`	Must be one of: `true`, `false`, `1`, `0`.	Required	Whether events are being delivered
`disabled_at`	Must be a String	Required	ISO 8601 time the subscription was disabled (nil allowed)
`disabled_reason`	Must be a String	Required	`disabled_by_user`, `failing` or `blocked_address` (nil allowed)
`last_delivery_at`	Must be a String	Required	ISO 8601 time of the most recent delivery attempt (nil allowed)
`last_delivery_status`	Must be a Integer	Required	HTTP status your URL returned on the most recent attempt (nil allowed)
`last_delivery_error`	Must be a String	Required	Why the most recent attempt failed (nil allowed)
`created_at`	Must be a String	Required	ISO 8601 creation timestamp
`updated_at`	Must be a String	Required	ISO 8601 last-update timestamp
`secret`	Must be a String	Required	Signing secret (`whsec_...`). Use it to verify the `webhook-signature` header.