API reference
Webhooks

Webhooks endpoints

Manage your webhooks, see how sending each event went, and send events again. What we send to a webhook, and how to check its signature, is in Webhooks.

These endpoints only work if we’ve turned on managing your own webhooks for you; otherwise they answer 403, and we manage your webhooks for you.

GET /partner/v1/webhooks - List webhooks

GET /partner/v1/webhooks

List webhooks

Responses

Status Description

200

Your webhooks.

array[Webhook]

200 body

application/json

Array items: Webhook

Field	Type	Description / Example
`id`	string \| null	Description The webhook’s ID.
`url`	string \| null	Description Where events are sent.
`events`	array[string]	Description The events it gets.
`enabled`	boolean	Description Whether events are being sent.
`disabledReason`	string \| null	Description Why we turned it off, if we did: for example, after a day of failed deliveries.
`createdAt`	string:date-time	Description When it was created (UTC).
`updatedAt`	string:date-time	Description When it was last changed (UTC).

403

Managing your own webhooks isn’t turned on for you.

ProblemDetails

403 body

application/json

Field	Type	Description / Example
`type`	string \| null
`title`	string \| null
`status`	integer:int32 \| null
`detail`	string \| null
`instance`	string \| null

Additional properties: any

POST /partner/v1/webhooks - Create a webhook

POST /partner/v1/webhooks

Create a webhook

The response has the webhook’s signing secret: keep it, as it isn’t shown again. You can have up to five webhooks.

Request Body

application/json

Field	Type	Description / Example
`url` *	string minLength: 1maxLength: 2000	Description Where to send events: an HTTPS URL on the internet. Example https://example.com/hooks/the-flower-factory
`events` *	array[string] minItems: 1	Description The events to send: `order.status_changed`, `order.shipment_added`, or both.

Responses

Status Description

201

The webhook was created, with its signing secret.

WebhookWithSecret

201 body

application/json

Field Type Description / Example

webhook

Webhook

Show fields

Field	Type	Description / Example
`id`	string \| null	Description The webhook’s ID.
`url`	string \| null	Description Where events are sent.
`events`	array[string]	Description The events it gets.
`enabled`	boolean	Description Whether events are being sent.
`disabledReason`	string \| null	Description Why we turned it off, if we did: for example, after a day of failed deliveries.
`createdAt`	string:date-time	Description When it was created (UTC).
`updatedAt`	string:date-time	Description When it was last changed (UTC).

Description

A webhook.

secret

string | null

Description

The secret to check event signatures with, in the Standard Webhooks format. Keep it safe: it’s only shown when the webhook is created and when the secret is replaced.

400

The URL or events aren’t valid, or you already have five webhooks.

ValidationProblemDetails

400 body

application/json

Field	Type	Description / Example
`type`	string \| null
`title`	string \| null
`status`	integer:int32 \| null
`detail`	string \| null
`instance`	string \| null
`errors`	map[string, array[string]]

Additional properties: any

403

Managing your own webhooks isn’t turned on for you.

ProblemDetails

403 body

application/json

Field	Type	Description / Example
`type`	string \| null
`title`	string \| null
`status`	integer:int32 \| null
`detail`	string \| null
`instance`	string \| null

Additional properties: any

GET /partner/v1/webhooks/{id} - Get a webhook

GET /partner/v1/webhooks/{id}

Get a webhook

Parameters

Name	In	Type	Description / Example
`id` *	path	string	Description The webhook’s ID.

Responses

Status Description

200

The webhook.

Webhook

200 body

application/json

Field	Type	Description / Example
`id`	string \| null	Description The webhook’s ID.
`url`	string \| null	Description Where events are sent.
`events`	array[string]	Description The events it gets.
`enabled`	boolean	Description Whether events are being sent.
`disabledReason`	string \| null	Description Why we turned it off, if we did: for example, after a day of failed deliveries.
`createdAt`	string:date-time	Description When it was created (UTC).
`updatedAt`	string:date-time	Description When it was last changed (UTC).

403

Managing your own webhooks isn’t turned on for you.

ProblemDetails

403 body

application/json

Field	Type	Description / Example
`type`	string \| null
`title`	string \| null
`status`	integer:int32 \| null
`detail`	string \| null
`instance`	string \| null

Additional properties: any

404

You don’t have a webhook with this ID.

ProblemDetails

404 body

application/json

Field	Type	Description / Example
`type`	string \| null
`title`	string \| null
`status`	integer:int32 \| null
`detail`	string \| null
`instance`	string \| null

Additional properties: any

PUT /partner/v1/webhooks/{id} - Update a webhook

PUT /partner/v1/webhooks/{id}

Update a webhook

Replaces the webhook’s URL, events and whether it’s on. Turn it back on here after we’ve turned it off.

Parameters

Name	In	Type	Description / Example
`id` *	path	string	Description The webhook’s ID.

Request Body

application/json

Field	Type	Description / Example
`url` *	string minLength: 1maxLength: 2000	Description Where to send events: an HTTPS URL on the internet. Example https://example.com/hooks/the-flower-factory
`events` *	array[string] minItems: 1	Description The events to send: `order.status_changed`, `order.shipment_added`, or both.
`enabled` *	boolean	Description Whether to send events. Turning a webhook back on after we turned it off (see `disabledReason`) sends events from then on.

Responses

Status Description

200

The webhook as it is now.

Webhook

200 body

application/json

Field	Type	Description / Example
`id`	string \| null	Description The webhook’s ID.
`url`	string \| null	Description Where events are sent.
`events`	array[string]	Description The events it gets.
`enabled`	boolean	Description Whether events are being sent.
`disabledReason`	string \| null	Description Why we turned it off, if we did: for example, after a day of failed deliveries.
`createdAt`	string:date-time	Description When it was created (UTC).
`updatedAt`	string:date-time	Description When it was last changed (UTC).

400

The URL or events aren’t valid.

ValidationProblemDetails

400 body

application/json

Field	Type	Description / Example
`type`	string \| null
`title`	string \| null
`status`	integer:int32 \| null
`detail`	string \| null
`instance`	string \| null
`errors`	map[string, array[string]]

Additional properties: any

403

Managing your own webhooks isn’t turned on for you.

ProblemDetails

403 body

application/json

Field	Type	Description / Example
`type`	string \| null
`title`	string \| null
`status`	integer:int32 \| null
`detail`	string \| null
`instance`	string \| null

Additional properties: any

404

You don’t have a webhook with this ID.

ProblemDetails

404 body

application/json

Field	Type	Description / Example
`type`	string \| null
`title`	string \| null
`status`	integer:int32 \| null
`detail`	string \| null
`instance`	string \| null

Additional properties: any

DELETE /partner/v1/webhooks/{id} - Delete a webhook

DELETE /partner/v1/webhooks/{id}

Delete a webhook

Stops its events at once, including any still being retried.

Parameters

Name	In	Type	Description / Example
`id` *	path	string	Description The webhook’s ID.

Responses

Status Description

204

The webhook was deleted.

403

Managing your own webhooks isn’t turned on for you.

ProblemDetails

403 body

application/json

Field	Type	Description / Example
`type`	string \| null
`title`	string \| null
`status`	integer:int32 \| null
`detail`	string \| null
`instance`	string \| null

Additional properties: any

404

You don’t have a webhook with this ID.

ProblemDetails

404 body

application/json

Field	Type	Description / Example
`type`	string \| null
`title`	string \| null
`status`	integer:int32 \| null
`detail`	string \| null
`instance`	string \| null

Additional properties: any

POST /partner/v1/webhooks/{id}/secret - Replace a webhook's secret

POST /partner/v1/webhooks/{id}/secret

Replace a webhook's secret

Events are signed with the new secret from now on, so update your endpoint straight away. The response has the new secret, which isn’t shown again.

Parameters

Name	In	Type	Description / Example
`id` *	path	string	Description The webhook’s ID.

Responses

Status Description

200

The webhook, with its new signing secret.

WebhookWithSecret

200 body

application/json

Field Type Description / Example

webhook

Webhook

Show fields

Field	Type	Description / Example
`id`	string \| null	Description The webhook’s ID.
`url`	string \| null	Description Where events are sent.
`events`	array[string]	Description The events it gets.
`enabled`	boolean	Description Whether events are being sent.
`disabledReason`	string \| null	Description Why we turned it off, if we did: for example, after a day of failed deliveries.
`createdAt`	string:date-time	Description When it was created (UTC).
`updatedAt`	string:date-time	Description When it was last changed (UTC).

Description

A webhook.

secret

string | null

Description

The secret to check event signatures with, in the Standard Webhooks format. Keep it safe: it’s only shown when the webhook is created and when the secret is replaced.

403

Managing your own webhooks isn’t turned on for you.

ProblemDetails

403 body

application/json

Field	Type	Description / Example
`type`	string \| null
`title`	string \| null
`status`	integer:int32 \| null
`detail`	string \| null
`instance`	string \| null

Additional properties: any

404

You don’t have a webhook with this ID.

ProblemDetails

404 body

application/json

Field	Type	Description / Example
`type`	string \| null
`title`	string \| null
`status`	integer:int32 \| null
`detail`	string \| null
`instance`	string \| null

Additional properties: any

GET /partner/v1/webhooks/{id}/deliveries - List a webhook's deliveries

GET /partner/v1/webhooks/{id}/deliveries

List a webhook's deliveries

Each event sent to the webhook and how sending it went, newest first. Pages are cursor-based: pass the previous page’s nextCursor as cursor.

Parameters

Name	In	Type	Description / Example
`id` *	path	string	Description The webhook’s ID.
`cursor`	query	string	Description The previous page’s `nextCursor`. Leave it out for the first page.
`pageSize`	query	integer:int32	Description Deliveries per page, 1 to 100.

Responses

Status Description

200

A page of deliveries.

WebhookDeliveryPage

200 body

application/json

Field Type Description / Example

items

array[WebhookDelivery]

Show fields

Field	Type	Description / Example
`id`	integer:int64	Description The delivery’s ID.
`eventId`	string \| null	Description The event’s ID: the `webhook-id` header, the same for every delivery of the event.
`eventType`	string \| null	Description The event’s type.
`orderReference`	string \| null	Description Your reference for the event’s order.
`status`	string \| null	Description `Pending` (still trying), `Delivered`, or `Failed` (we’ve stopped trying).
`attempts`	integer:int32	Description How many times we’ve tried.
`lastAttemptAt`	string:date-time \| null	Description When we last tried (UTC).
`nextAttemptAt`	string:date-time \| null	Description When we’ll try next (UTC), while it’s pending.
`lastResponseStatus`	integer:int32 \| null	Description The HTTP status your endpoint last answered with, if it answered.
`lastError`	string \| null	Description Why the last attempt failed.
`createdAt`	string:date-time	Description When the event happened (UTC).

Description

This page’s deliveries, newest first.

nextCursor

string | null

Description

Pass as cursor to get the next page; null on the last page.

400

The cursor or page size isn’t valid.

ValidationProblemDetails

400 body

application/json

Field	Type	Description / Example
`type`	string \| null
`title`	string \| null
`status`	integer:int32 \| null
`detail`	string \| null
`instance`	string \| null
`errors`	map[string, array[string]]

Additional properties: any

403

Managing your own webhooks isn’t turned on for you.

ProblemDetails

403 body

application/json

Field	Type	Description / Example
`type`	string \| null
`title`	string \| null
`status`	integer:int32 \| null
`detail`	string \| null
`instance`	string \| null

Additional properties: any

404

You don’t have a webhook with this ID.

ProblemDetails

404 body

application/json

Field	Type	Description / Example
`type`	string \| null
`title`	string \| null
`status`	integer:int32 \| null
`detail`	string \| null
`instance`	string \| null

Additional properties: any

POST /partner/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver - Send an event again

POST /partner/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver

Send an event again

Sends a delivery’s event to the webhook again, with the same webhook-id, as a new delivery. Use it after fixing your endpoint, or to test it.

Parameters

Name	In	Type	Description / Example
`id` *	path	string	Description The webhook’s ID.
`deliveryId` *	path	integer:int64	Description The delivery’s ID.

Responses

Status Description

202

The event will be sent again shortly: this is the new delivery.

WebhookDelivery

202 body

application/json

Field	Type	Description / Example
`id`	integer:int64	Description The delivery’s ID.
`eventId`	string \| null	Description The event’s ID: the `webhook-id` header, the same for every delivery of the event.
`eventType`	string \| null	Description The event’s type.
`orderReference`	string \| null	Description Your reference for the event’s order.
`status`	string \| null	Description `Pending` (still trying), `Delivered`, or `Failed` (we’ve stopped trying).
`attempts`	integer:int32	Description How many times we’ve tried.
`lastAttemptAt`	string:date-time \| null	Description When we last tried (UTC).
`nextAttemptAt`	string:date-time \| null	Description When we’ll try next (UTC), while it’s pending.
`lastResponseStatus`	integer:int32 \| null	Description The HTTP status your endpoint last answered with, if it answered.
`lastError`	string \| null	Description Why the last attempt failed.
`createdAt`	string:date-time	Description When the event happened (UTC).

403

Managing your own webhooks isn’t turned on for you.

ProblemDetails

403 body

application/json

Field	Type	Description / Example
`type`	string \| null
`title`	string \| null
`status`	integer:int32 \| null
`detail`	string \| null
`instance`	string \| null

Additional properties: any

404

You don’t have this webhook, or it has no such delivery.

ProblemDetails

404 body

application/json

Field	Type	Description / Example
`type`	string \| null
`title`	string \| null
`status`	integer:int32 \| null
`detail`	string \| null
`instance`	string \| null

Additional properties: any

409

The webhook is turned off.

ProblemDetails

409 body

application/json

Field	Type	Description / Example
`type`	string \| null
`title`	string \| null
`status`	integer:int32 \| null
`detail`	string \| null
`instance`	string \| null

Additional properties: any

Webhooks endpoints

Webhooks endpoints

GET /partner/v1/webhooks - List webhooks

Responses

POST /partner/v1/webhooks - Create a webhook

Request Body

Responses

GET /partner/v1/webhooks/{id} - Get a webhook

Parameters

Responses

PUT /partner/v1/webhooks/{id} - Update a webhook

Parameters

Request Body

Responses

DELETE /partner/v1/webhooks/{id} - Delete a webhook

Parameters

Responses

POST /partner/v1/webhooks/{id}/secret - Replace a webhook's secret

Parameters

Responses

GET /partner/v1/webhooks/{id}/deliveries - List a webhook's deliveries

Parameters

Responses

POST /partner/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver - Send an event again

Parameters

Responses

On This Page