Webhook endpoints

Create and manage the store's webhook endpoints, and follow their deliveries.

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 read_webhooks

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

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.

  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.

List webhook topics

GET read_webhooks

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

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.

  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.

Get a webhook topic schema

GET read_webhooks

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.

Example: orders/create

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.

  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.

  • 400 WEBHOOK_UNKNOWN_EVENT_TYPE

    The topic does not exist.

  • 403 WEBHOOK_EVENT_PERMISSION_DENIED

    The token's scopes do not cover this topic.

  • 400 STORE_API_QUERY_PARAMETER_UNKNOWN

    The query string has a parameter this request does not accept. The message and error.details.allowed_parameters list the ones it does.

List webhook endpoints

GET read_webhooks

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.

Example: orders
status string

active, inactive or auto_disabled.

Example: active
limit integer

Page size, up to list_max_limit.

Example: 20
offset integer

Rows to skip.

Default: 0
Example: 0

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.

  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.

  • 400 WEBHOOK_INVALID_STATUS_FILTER

    The status filter is not active, inactive or auto_disabled.

  • 400 WEBHOOK_SEARCH_TOO_LONG

    The search is longer than search_max_length.

  • 400 WEBHOOK_LIST_INVALID_LIMIT

    The limit is outside the allowed range.

  • 400 WEBHOOK_OFFSET_NEGATIVE

    The offset is negative.

  • 400 STORE_API_QUERY_PARAMETER_UNKNOWN

    The query string has a parameter this request does not accept. The message and error.details.allowed_parameters list the ones it does.

Get a webhook endpoint

GET read_webhooks

Get one webhook endpoint.

The signing secret is never returned here.

Path parameters

Name Type Description
endpointId required string

Webhook endpoint id.

Example: 3f1d6a2e-7b4c-4e1a-9c8d-2b5e6f7a8c90

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.

  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.

  • 404 WEBHOOK_ENDPOINT_NOT_FOUND

    The endpoint does not exist in this store.

  • 403 WEBHOOK_EVENT_PERMISSION_DENIED

    The endpoint subscribes to a topic the token's scopes do not cover.

Create a webhook endpoint

POST write_webhooks

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.

Example: Order sync
url required string

HTTPS URL that resolves only to public IP addresses.

Example: https://example.com/tringify/webhooks
description string

Optional note, up to description_max_length characters.

Example: Sends orders to the warehouse system.
subscribed_events required array<string>

Topics to deliver, from the topics list. Each needs the token's scope for it.

Example: ["orders/create","orders/paid"]
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.

Example: {"orders/create":["order.id","order.total"]}

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.

  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.

  • 400 INVALID_INPUT

    The body is not valid JSON or has an unknown field.

  • 400 WEBHOOK_NAME_REQUIRED

    A name is required.

  • 400 WEBHOOK_NAME_TOO_LONG

    The name is longer than name_max_length.

  • 400 WEBHOOK_NAME_INVALID_CHARS

    The name contains characters that are not allowed.

  • 400 WEBHOOK_DESCRIPTION_TOO_LONG

    The description is longer than description_max_length.

  • 400 WEBHOOK_DESCRIPTION_INVALID_CHARS

    The description contains characters that are not allowed.

  • 400 WEBHOOK_URL_REQUIRED

    A URL is required.

  • 400 WEBHOOK_URL_INVALID

    The URL is not valid.

  • 400 WEBHOOK_URL_MUST_BE_HTTPS

    The URL does not use HTTPS.

  • 400 WEBHOOK_URL_TOO_LONG

    The URL is longer than url_max_length.

  • 400 WEBHOOK_URL_PRIVATE_ADDRESS

    The URL resolves to a private or reserved IP address.

  • 400 WEBHOOK_URL_UNRESOLVABLE

    The URL's host name could not be resolved.

  • 400 WEBHOOK_UNKNOWN_EVENT_TYPE

    A topic in subscribed_events does not exist.

  • 400 WEBHOOK_DUPLICATE_EVENT

    A topic is listed more than once.

  • 400 WEBHOOK_TOO_MANY_EVENTS

    More topics than max_events_per_endpoint.

  • 403 WEBHOOK_EVENT_PERMISSION_DENIED

    A topic in subscribed_events needs a scope the token does not hold.

  • 400 WEBHOOK_PROJECTION_NOT_SUBSCRIBED

    field_projection names a topic that is not subscribed.

  • 400 WEBHOOK_PROJECTION_UNKNOWN_EVENT

    field_projection is not supported for that topic.

  • 400 WEBHOOK_PROJECTION_UNKNOWN_PATH

    field_projection names a field the topic does not have.

  • 400 WEBHOOK_PROJECTION_MISSING_REQUIRED

    field_projection leaves out a field that is always present.

  • 400 WEBHOOK_PROJECTION_NO_FIELDS

    field_projection selects no field for a topic.

  • 400 WEBHOOK_ENDPOINT_LIMIT_REACHED

    The store already has max_endpoints_per_store endpoints.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Update a webhook endpoint

PUT write_webhooks

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.

Example: 3f1d6a2e-7b4c-4e1a-9c8d-2b5e6f7a8c90

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.

Example: Order sync
url string

HTTPS URL that resolves only to public IP addresses.

Example: https://example.com/tringify/webhooks
description string

Optional note, up to description_max_length characters.

Example: Sends orders to the warehouse system.
subscribed_events array<string>

Topics to deliver, from the topics list. Each needs the token's scope for it.

Example: ["orders/create","orders/paid"]
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.

Example: {"orders/create":["order.id","order.total"]}
is_active boolean

false pauses deliveries; true resumes them, including an auto-disabled endpoint.

Example: true

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.

  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.

  • 404 WEBHOOK_ENDPOINT_NOT_FOUND

    The endpoint does not exist in this store.

  • 403 WEBHOOK_EVENT_PERMISSION_DENIED

    The 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.

  • 400 INVALID_INPUT

    The body is not valid JSON or has an unknown field.

  • 400 WEBHOOK_NAME_REQUIRED

    A name is required.

  • 400 WEBHOOK_NAME_TOO_LONG

    The name is longer than name_max_length.

  • 400 WEBHOOK_NAME_INVALID_CHARS

    The name contains characters that are not allowed.

  • 400 WEBHOOK_DESCRIPTION_TOO_LONG

    The description is longer than description_max_length.

  • 400 WEBHOOK_DESCRIPTION_INVALID_CHARS

    The description contains characters that are not allowed.

  • 400 WEBHOOK_URL_REQUIRED

    A URL is required.

  • 400 WEBHOOK_URL_INVALID

    The URL is not valid.

  • 400 WEBHOOK_URL_MUST_BE_HTTPS

    The URL does not use HTTPS.

  • 400 WEBHOOK_URL_TOO_LONG

    The URL is longer than url_max_length.

  • 400 WEBHOOK_URL_PRIVATE_ADDRESS

    The URL resolves to a private or reserved IP address.

  • 400 WEBHOOK_URL_UNRESOLVABLE

    The URL's host name could not be resolved.

  • 400 WEBHOOK_UNKNOWN_EVENT_TYPE

    A topic in subscribed_events does not exist.

  • 400 WEBHOOK_DUPLICATE_EVENT

    A topic is listed more than once.

  • 400 WEBHOOK_TOO_MANY_EVENTS

    More topics than max_events_per_endpoint.

  • 400 WEBHOOK_PROJECTION_NOT_SUBSCRIBED

    field_projection names a topic that is not subscribed.

  • 400 WEBHOOK_PROJECTION_UNKNOWN_EVENT

    field_projection is not supported for that topic.

  • 400 WEBHOOK_PROJECTION_UNKNOWN_PATH

    field_projection names a field the topic does not have.

  • 400 WEBHOOK_PROJECTION_MISSING_REQUIRED

    field_projection leaves out a field that is always present.

  • 400 WEBHOOK_PROJECTION_NO_FIELDS

    field_projection selects no field for a topic.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Delete a webhook endpoint

DELETE write_webhooks

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.

Example: 3f1d6a2e-7b4c-4e1a-9c8d-2b5e6f7a8c90

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
confirmed boolean

Send true with the token from CONFIRMATION_REQUIRED to carry out the action.

Example: true
confirmation_token string

Single-use token returned by CONFIRMATION_REQUIRED.

Example: confirm_...

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.

  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.

  • 404 WEBHOOK_ENDPOINT_NOT_FOUND

    The endpoint does not exist in this store.

  • 403 WEBHOOK_EVENT_PERMISSION_DENIED

    The endpoint subscribes to a topic the token's scopes do not cover.

  • 409 CONFIRMATION_REQUIRED

    First request: the response carries the impact and a confirmation_token.

  • 400 WEBHOOK_CONFIRMATION_INVALID

    The confirmation_token is missing, expired or for another action.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Rotate a signing secret

POST write_webhooks

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.

Example: 3f1d6a2e-7b4c-4e1a-9c8d-2b5e6f7a8c90

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
confirmed boolean

Send true with the token from CONFIRMATION_REQUIRED to carry out the action.

Example: true
confirmation_token string

Single-use token returned by CONFIRMATION_REQUIRED.

Example: confirm_...

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.

  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.

  • 404 WEBHOOK_ENDPOINT_NOT_FOUND

    The endpoint does not exist in this store.

  • 403 WEBHOOK_EVENT_PERMISSION_DENIED

    The endpoint subscribes to a topic the token's scopes do not cover.

  • 409 CONFIRMATION_REQUIRED

    First request: the response carries the impact and a confirmation_token.

  • 400 WEBHOOK_CONFIRMATION_INVALID

    The confirmation_token is missing, expired or for another action.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Send a test delivery

POST write_webhooks

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.

Example: 3f1d6a2e-7b4c-4e1a-9c8d-2b5e6f7a8c90

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.

  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.

  • 404 WEBHOOK_ENDPOINT_NOT_FOUND

    The endpoint does not exist in this store.

  • 403 WEBHOOK_EVENT_PERMISSION_DENIED

    The endpoint subscribes to a topic the token's scopes do not cover.

  • 400 WEBHOOK_ENDPOINT_INACTIVE

    The endpoint is paused.

  • 400 WEBHOOK_ENDPOINT_AUTO_DISABLED

    The endpoint was disabled after repeated failures; resume it first.

  • 429 WEBHOOK_TEST_TOO_SOON

    A test was sent moments ago; wait and send again.

List deliveries

GET read_webhooks

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.

Example: 3f1d6a2e-7b4c-4e1a-9c8d-2b5e6f7a8c90

Query parameters

Name Type Description
event_type string

Only deliveries of this topic.

Example: orders/create
status string

A value from status_options in the limits.

Example: failed
from_date string

First day, YYYY-MM-DD in the store's time zone.

Example: 2026-11-01
to_date string

Last day, YYYY-MM-DD in the store's time zone.

Example: 2026-11-05
limit integer

Page size, up to 100.

Example: 50
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

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.

  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.

  • 404 WEBHOOK_ENDPOINT_NOT_FOUND

    The endpoint does not exist in this store.

  • 403 WEBHOOK_EVENT_PERMISSION_DENIED

    The endpoint subscribes to a topic the token's scopes do not cover.

  • 400 WEBHOOK_INVALID_STATUS_FILTER

    The status filter is not one of status_options from the limits.

  • 400 WEBHOOK_DELIVERY_CURSOR_INVALID

    The cursor is no longer valid; start again from the first page.

  • 400 STORE_API_QUERY_PARAMETER_UNKNOWN

    The query string has a parameter this request does not accept. The message and error.details.allowed_parameters list the ones it does.

List delivery attempts

GET read_webhooks

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.

Example: 3f1d6a2e-7b4c-4e1a-9c8d-2b5e6f7a8c90
deliveryId required string

Delivery id from the deliveries list.

Example: 8b2e4c6a-1d3f-4a5b-9c7e-0f2a4b6c8d1e

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.

  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.

  • 404 WEBHOOK_ENDPOINT_NOT_FOUND

    The endpoint does not exist in this store.

  • 403 WEBHOOK_EVENT_PERMISSION_DENIED

    The endpoint subscribes to a topic the token's scopes do not cover.

  • 404 WEBHOOK_DELIVERY_NOT_FOUND

    The delivery does not exist for this endpoint.

Retry a delivery

POST write_webhooks

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.

Example: 3f1d6a2e-7b4c-4e1a-9c8d-2b5e6f7a8c90
deliveryId required string

Delivery id from the deliveries list.

Example: 8b2e4c6a-1d3f-4a5b-9c7e-0f2a4b6c8d1e

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.

  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.

  • 404 WEBHOOK_ENDPOINT_NOT_FOUND

    The endpoint does not exist in this store.

  • 403 WEBHOOK_EVENT_PERMISSION_DENIED

    The endpoint subscribes to a topic the token's scopes do not cover.

  • 404 WEBHOOK_DELIVERY_NOT_RETRYABLE

    The delivery does not exist or has not failed.