Webhook endpoints are the store's own: the same endpoints Store Admin manages under Settings > Webhooks. Only the store's admin token can manage them; reads need read_webhooks and changes need write_webhooks. Apps receive events through their own subscription instead; see App webhooks.
Each topic an endpoint subscribes to needs the token's scope for the data it carries, for example read_orders for orders/create; the topics list shows only the topics your token can use. Creating an endpoint returns its signing_secret once, and rotating returns the new one once. How deliveries are signed, retried and merged is in Receive webhooks.
Deleting an endpoint and rotating its secret ask for confirmation first: the first request answers CONFIRMATION_REQUIRED with a confirmation_token, and the repeat with confirmed: true and that token carries the action out.
Endpoints#
Webhook limits
Get webhook endpoint limits and usage.
Returns the endpoint and topic limits, current usage, the retry schedule (retry_backoff_seconds, max_attempts), the auto-disable threshold, the paused-event limits and the delivery and endpoint status filter values with their labels.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
402SUBSCRIPTION_REQUIREDThe store does not have an active or trialing subscription.
-
403STORE_API_SCOPE_REQUIREDToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDThe token's request allowance is exhausted. Retry after the Retry-After header.
List webhook topics
List the topics this token can subscribe to.
Lists only the topics the token's scopes allow: each topic needs the read scope of the data it carries, for example read_orders for orders/create. Each topic has its label, description, category_label and required_scope.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
402SUBSCRIPTION_REQUIREDThe store does not have an active or trialing subscription.
-
403STORE_API_SCOPE_REQUIREDToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDThe token's request allowance is exhausted. Retry after the Retry-After header.
Get a webhook topic schema
Show the payload fields of one topic.
Returns the data object of the delivery envelope as a tree of path, type, required and nullable. Fields marked always present cannot be left out by field_projection.
Query parameters
| Name | Type | Description |
|---|---|---|
event_type
required
|
string |
Topic name. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
402SUBSCRIPTION_REQUIREDThe store does not have an active or trialing subscription.
-
403STORE_API_SCOPE_REQUIREDToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDThe token's request allowance is exhausted. Retry after the Retry-After header.
-
400WEBHOOK_UNKNOWN_EVENT_TYPEThe topic does not exist.
-
403WEBHOOK_EVENT_PERMISSION_DENIEDThe token's scopes do not cover this topic.
-
400STORE_API_QUERY_PARAMETER_UNKNOWNThe query string has a parameter this request does not accept. The message and
error.details.allowed_parameterslist the ones it does.
List webhook endpoints
List the store's webhook endpoints.
Each endpoint has status (active, inactive or auto_disabled) and status_label. blocked_event names the first subscribed topic the token's scopes do not cover; while it is set, the token cannot change, rotate, delete or retry that endpoint. The signing secret is never returned here.
Query parameters
| Name | Type | Description |
|---|---|---|
search
|
string |
Search name or URL. |
status
|
string |
active, inactive or auto_disabled. |
limit
|
integer |
Page size, up to list_max_limit. |
offset
|
integer |
Rows to skip. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
402SUBSCRIPTION_REQUIREDThe store does not have an active or trialing subscription.
-
403STORE_API_SCOPE_REQUIREDToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDThe token's request allowance is exhausted. Retry after the Retry-After header.
-
400WEBHOOK_INVALID_STATUS_FILTERThe status filter is not active, inactive or auto_disabled.
-
400WEBHOOK_SEARCH_TOO_LONGThe search is longer than search_max_length.
-
400WEBHOOK_LIST_INVALID_LIMITThe limit is outside the allowed range.
-
400WEBHOOK_OFFSET_NEGATIVEThe offset is negative.
-
400STORE_API_QUERY_PARAMETER_UNKNOWNThe query string has a parameter this request does not accept. The message and
error.details.allowed_parameterslist the ones it does.
Get a webhook endpoint
Get one webhook endpoint.
The signing secret is never returned here.
Path parameters
| Name | Type | Description |
|---|---|---|
endpointId
required
|
string |
Webhook endpoint id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
402SUBSCRIPTION_REQUIREDThe store does not have an active or trialing subscription.
-
403STORE_API_SCOPE_REQUIREDToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDThe token's request allowance is exhausted. Retry after the Retry-After header.
-
404WEBHOOK_ENDPOINT_NOT_FOUNDThe endpoint does not exist in this store.
-
403WEBHOOK_EVENT_PERMISSION_DENIEDThe endpoint subscribes to a topic the token's scopes do not cover.
Create a webhook endpoint
Create a webhook endpoint and get its signing secret.
The response carries signing_secret, shown only this once: store it to verify deliveries, as described in Receive webhooks. The URL must use HTTPS and resolve only to public IP addresses. Every topic in subscribed_events needs the token's scope for it.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
name
required
|
string |
Endpoint name, up to name_max_length characters. |
url
required
|
string |
HTTPS URL that resolves only to public IP addresses. |
description
|
string |
Optional note, up to description_max_length characters. |
subscribed_events
required
|
array<string> |
Topics to deliver, from the topics list. Each needs the token's scope for it. |
field_projection
|
object |
Per topic, the payload fields to send, as paths from the topic schema. Omit a topic to send every field. Fields marked always present are always sent. |
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
402SUBSCRIPTION_REQUIREDThe store does not have an active or trialing subscription.
-
403STORE_API_SCOPE_REQUIREDToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDThe token's request allowance is exhausted. Retry after the Retry-After header.
-
400INVALID_INPUTThe body is not valid JSON or has an unknown field.
-
400WEBHOOK_NAME_REQUIREDA name is required.
-
400WEBHOOK_NAME_TOO_LONGThe name is longer than name_max_length.
-
400WEBHOOK_NAME_INVALID_CHARSThe name contains characters that are not allowed.
-
400WEBHOOK_DESCRIPTION_TOO_LONGThe description is longer than description_max_length.
-
400WEBHOOK_DESCRIPTION_INVALID_CHARSThe description contains characters that are not allowed.
-
400WEBHOOK_URL_REQUIREDA URL is required.
-
400WEBHOOK_URL_INVALIDThe URL is not valid.
-
400WEBHOOK_URL_MUST_BE_HTTPSThe URL does not use HTTPS.
-
400WEBHOOK_URL_TOO_LONGThe URL is longer than url_max_length.
-
400WEBHOOK_URL_PRIVATE_ADDRESSThe URL resolves to a private or reserved IP address.
-
400WEBHOOK_URL_UNRESOLVABLEThe URL's host name could not be resolved.
-
400WEBHOOK_UNKNOWN_EVENT_TYPEA topic in subscribed_events does not exist.
-
400WEBHOOK_DUPLICATE_EVENTA topic is listed more than once.
-
400WEBHOOK_TOO_MANY_EVENTSMore topics than max_events_per_endpoint.
-
403WEBHOOK_EVENT_PERMISSION_DENIEDA topic in subscribed_events needs a scope the token does not hold.
-
400WEBHOOK_PROJECTION_NOT_SUBSCRIBEDfield_projection names a topic that is not subscribed.
-
400WEBHOOK_PROJECTION_UNKNOWN_EVENTfield_projection is not supported for that topic.
-
400WEBHOOK_PROJECTION_UNKNOWN_PATHfield_projection names a field the topic does not have.
-
400WEBHOOK_PROJECTION_MISSING_REQUIREDfield_projection leaves out a field that is always present.
-
400WEBHOOK_PROJECTION_NO_FIELDSfield_projection selects no field for a topic.
-
400WEBHOOK_ENDPOINT_LIMIT_REACHEDThe store already has max_endpoints_per_store endpoints.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Update a webhook endpoint
Change an endpoint's name, URL, topics, fields or state.
Send only the fields to change. subscribed_events replaces the whole list. Set is_active to false to pause deliveries and true to resume them; resuming an auto-disabled endpoint also delivers the events held while it was disabled.
Path parameters
| Name | Type | Description |
|---|---|---|
endpointId
required
|
string |
Webhook endpoint id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
name
|
string |
Endpoint name, up to name_max_length characters. |
url
|
string |
HTTPS URL that resolves only to public IP addresses. |
description
|
string |
Optional note, up to description_max_length characters. |
subscribed_events
|
array<string> |
Topics to deliver, from the topics list. Each needs the token's scope for it. |
field_projection
|
object |
Per topic, the payload fields to send, as paths from the topic schema. Omit a topic to send every field. Fields marked always present are always sent. |
is_active
|
boolean |
|
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
402SUBSCRIPTION_REQUIREDThe store does not have an active or trialing subscription.
-
403STORE_API_SCOPE_REQUIREDToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDThe token's request allowance is exhausted. Retry after the Retry-After header.
-
404WEBHOOK_ENDPOINT_NOT_FOUNDThe endpoint does not exist in this store.
-
403WEBHOOK_EVENT_PERMISSION_DENIEDThe endpoint subscribes to a topic the token's scopes do not cover. A topic in subscribed_events needs a scope the token does not hold.
-
400INVALID_INPUTThe body is not valid JSON or has an unknown field.
-
400WEBHOOK_NAME_REQUIREDA name is required.
-
400WEBHOOK_NAME_TOO_LONGThe name is longer than name_max_length.
-
400WEBHOOK_NAME_INVALID_CHARSThe name contains characters that are not allowed.
-
400WEBHOOK_DESCRIPTION_TOO_LONGThe description is longer than description_max_length.
-
400WEBHOOK_DESCRIPTION_INVALID_CHARSThe description contains characters that are not allowed.
-
400WEBHOOK_URL_REQUIREDA URL is required.
-
400WEBHOOK_URL_INVALIDThe URL is not valid.
-
400WEBHOOK_URL_MUST_BE_HTTPSThe URL does not use HTTPS.
-
400WEBHOOK_URL_TOO_LONGThe URL is longer than url_max_length.
-
400WEBHOOK_URL_PRIVATE_ADDRESSThe URL resolves to a private or reserved IP address.
-
400WEBHOOK_URL_UNRESOLVABLEThe URL's host name could not be resolved.
-
400WEBHOOK_UNKNOWN_EVENT_TYPEA topic in subscribed_events does not exist.
-
400WEBHOOK_DUPLICATE_EVENTA topic is listed more than once.
-
400WEBHOOK_TOO_MANY_EVENTSMore topics than max_events_per_endpoint.
-
400WEBHOOK_PROJECTION_NOT_SUBSCRIBEDfield_projection names a topic that is not subscribed.
-
400WEBHOOK_PROJECTION_UNKNOWN_EVENTfield_projection is not supported for that topic.
-
400WEBHOOK_PROJECTION_UNKNOWN_PATHfield_projection names a field the topic does not have.
-
400WEBHOOK_PROJECTION_MISSING_REQUIREDfield_projection leaves out a field that is always present.
-
400WEBHOOK_PROJECTION_NO_FIELDSfield_projection selects no field for a topic.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Delete a webhook endpoint
Delete an endpoint and its delivery log.
The first request answers CONFIRMATION_REQUIRED (409) with the impact (pending deliveries and log entries that will be removed) and a confirmation_token. Send the request again with confirmed: true and that token to delete. Deletion cannot be undone.
Path parameters
| Name | Type | Description |
|---|---|---|
endpointId
required
|
string |
Webhook endpoint id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
confirmed
|
boolean |
Send |
confirmation_token
|
string |
Single-use token returned by |
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
402SUBSCRIPTION_REQUIREDThe store does not have an active or trialing subscription.
-
403STORE_API_SCOPE_REQUIREDToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDThe token's request allowance is exhausted. Retry after the Retry-After header.
-
404WEBHOOK_ENDPOINT_NOT_FOUNDThe endpoint does not exist in this store.
-
403WEBHOOK_EVENT_PERMISSION_DENIEDThe endpoint subscribes to a topic the token's scopes do not cover.
-
409CONFIRMATION_REQUIREDFirst request: the response carries the impact and a confirmation_token.
-
400WEBHOOK_CONFIRMATION_INVALIDThe confirmation_token is missing, expired or for another action.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Rotate a signing secret
Replace an endpoint's signing secret.
The first request answers CONFIRMATION_REQUIRED (409) and a confirmation_token. Send it again with confirmed: true and the token: the response carries the new signing_secret, shown only this once. The old secret stops working at once, so deploy the new one straight away.
Path parameters
| Name | Type | Description |
|---|---|---|
endpointId
required
|
string |
Webhook endpoint id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
confirmed
|
boolean |
Send |
confirmation_token
|
string |
Single-use token returned by |
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
402SUBSCRIPTION_REQUIREDThe store does not have an active or trialing subscription.
-
403STORE_API_SCOPE_REQUIREDToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDThe token's request allowance is exhausted. Retry after the Retry-After header.
-
404WEBHOOK_ENDPOINT_NOT_FOUNDThe endpoint does not exist in this store.
-
403WEBHOOK_EVENT_PERMISSION_DENIEDThe endpoint subscribes to a topic the token's scopes do not cover.
-
409CONFIRMATION_REQUIREDFirst request: the response carries the impact and a confirmation_token.
-
400WEBHOOK_CONFIRMATION_INVALIDThe confirmation_token is missing, expired or for another action.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Send a test delivery
Send a signed test delivery to the endpoint.
Sends a delivery with event test, signed like any other, and records it in the delivery log. Wait between tests; a test sent too soon answers WEBHOOK_TEST_TOO_SOON.
Path parameters
| Name | Type | Description |
|---|---|---|
endpointId
required
|
string |
Webhook endpoint id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
402SUBSCRIPTION_REQUIREDThe store does not have an active or trialing subscription.
-
403STORE_API_SCOPE_REQUIREDToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDThe token's request allowance is exhausted. Retry after the Retry-After header.
-
404WEBHOOK_ENDPOINT_NOT_FOUNDThe endpoint does not exist in this store.
-
403WEBHOOK_EVENT_PERMISSION_DENIEDThe endpoint subscribes to a topic the token's scopes do not cover.
-
400WEBHOOK_ENDPOINT_INACTIVEThe endpoint is paused.
-
400WEBHOOK_ENDPOINT_AUTO_DISABLEDThe endpoint was disabled after repeated failures; resume it first.
-
429WEBHOOK_TEST_TOO_SOONA test was sent moments ago; wait and send again.
List deliveries
List an endpoint's deliveries, newest first.
Deliveries are listed without payloads. Each has event_label and status_label. Omit cursor for the first page; pass next_cursor (older) or previous_cursor (newer) from a response to move, and start again without a cursor when a filter changes. total counts matching deliveries exactly up to 10,000; above that total_capped is true.
Path parameters
| Name | Type | Description |
|---|---|---|
endpointId
required
|
string |
Webhook endpoint id. |
Query parameters
| Name | Type | Description |
|---|---|---|
event_type
|
string |
Only deliveries of this topic. |
status
|
string |
A value from status_options in the limits. |
from_date
|
string |
First day, YYYY-MM-DD in the store's time zone. |
to_date
|
string |
Last day, YYYY-MM-DD in the store's time zone. |
limit
|
integer |
Page size, up to 100. |
cursor
|
string |
next_cursor or previous_cursor from the previous response, with the same filters. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
402SUBSCRIPTION_REQUIREDThe store does not have an active or trialing subscription.
-
403STORE_API_SCOPE_REQUIREDToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDThe token's request allowance is exhausted. Retry after the Retry-After header.
-
404WEBHOOK_ENDPOINT_NOT_FOUNDThe endpoint does not exist in this store.
-
403WEBHOOK_EVENT_PERMISSION_DENIEDThe endpoint subscribes to a topic the token's scopes do not cover.
-
400WEBHOOK_INVALID_STATUS_FILTERThe status filter is not one of status_options from the limits.
-
400WEBHOOK_DELIVERY_CURSOR_INVALIDThe cursor is no longer valid; start again from the first page.
-
400STORE_API_QUERY_PARAMETER_UNKNOWNThe query string has a parameter this request does not accept. The message and
error.details.allowed_parameterslist the ones it does.
List delivery attempts
List the attempts of one delivery.
Each attempt has its response status, error and duration.
Path parameters
| Name | Type | Description |
|---|---|---|
endpointId
required
|
string |
Webhook endpoint id. |
deliveryId
required
|
string |
Delivery id from the deliveries list. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
402SUBSCRIPTION_REQUIREDThe store does not have an active or trialing subscription.
-
403STORE_API_SCOPE_REQUIREDToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDThe token's request allowance is exhausted. Retry after the Retry-After header.
-
404WEBHOOK_ENDPOINT_NOT_FOUNDThe endpoint does not exist in this store.
-
403WEBHOOK_EVENT_PERMISSION_DENIEDThe endpoint subscribes to a topic the token's scopes do not cover.
-
404WEBHOOK_DELIVERY_NOT_FOUNDThe delivery does not exist for this endpoint.
Retry a delivery
Send a failed delivery again.
Queues the delivery for another attempt, with a new timestamp and signature and the same delivery_id.
Path parameters
| Name | Type | Description |
|---|---|---|
endpointId
required
|
string |
Webhook endpoint id. |
deliveryId
required
|
string |
Delivery id from the deliveries list. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
402SUBSCRIPTION_REQUIREDThe store does not have an active or trialing subscription.
-
403STORE_API_SCOPE_REQUIREDToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDThe token's request allowance is exhausted. Retry after the Retry-After header.
-
404WEBHOOK_ENDPOINT_NOT_FOUNDThe endpoint does not exist in this store.
-
403WEBHOOK_EVENT_PERMISSION_DENIEDThe endpoint subscribes to a topic the token's scopes do not cover.
-
404WEBHOOK_DELIVERY_NOT_RETRYABLEThe delivery does not exist or has not failed.