Webhook endpoints

The addresses the shop sends its events to: orders, products, customers, quotations and enquiries.

Reach them through admin.webhooks. Reading needs the webhooks:read scope, changing them webhooks:write. An endpoint takes only events your key may read: order events need orders:read, product events and catalog.changed products:read, customer events customers:read, and quotation and enquiry events quotations:read. An app sees and manages only the endpoints it made, which are deleted when the merchant disconnects it. Check each delivery with verifyWebhookSignature.

List webhook endpoints

admin.webhooks.list(query?: ListQuery): Promise<CursorPage<WebhookEndpoint>>

One page of the endpoints your key may see, newest first, or oldest change first with updatedSince. Read the next page with meta.nextCursor as cursor. Scope: webhooks:read.

Parameters

Query fields

Returns

A CursorPage<WebhookEndpoint>:

Errors

Example

const { data: endpoints } = await admin.webhooks.list();

Iterate over every endpoint

admin.webhooks.all(query?: ListQuery): AsyncGenerator<WebhookEndpoint, void, undefined>

Every endpoint matching the query, one at a time, fetching the next page as you read. It takes the same query as list, without cursor. Scope: webhooks:read.

Returns

An async iterable of WebhookEndpoint, each:

Example

for await (const endpoint of admin.webhooks.all()) {
    if (!endpoint.active) {
        await admin.webhooks.update(endpoint.id, { active: true });
    }
}

Get a webhook endpoint

admin.webhooks.get(id: number): Promise<WebhookEndpoint>

One endpoint by its id. Scope: webhooks:read.

Parameters

Returns

A WebhookEndpoint:

Errors

Add a webhook endpoint

admin.webhooks.create(input: WebhookEndpointInput, options?: RequestOptions): Promise<CreatedWebhookEndpoint>

A new endpoint, which starts on. Its whsec_… signing secret is returned in secret, only this once: keep it to verify deliveries. A shop has at most 10 endpoints (422 limit_reached). Scope: webhooks:write, plus the read scope of each event.

Parameters

Request fields

Returns

A CreatedWebhookEndpoint: the endpoint in data, and its secret:

Errors

Example

const { data: endpoint, secret } = await admin.webhooks.create({
    url: 'https://erp.example.com/storehugs/webhooks',
    events: ['order.created', 'order.status_changed', 'product.stock_changed'],
});
// Keep secret to verify deliveries.

Update a webhook endpoint

admin.webhooks.update(id: number, changes: Partial<WebhookEndpointInput>, options?: UpdateOptions): Promise<WebhookEndpoint>

Changes the address, the events or whether the endpoint is on; only what is sent changes. Turning it on resets its failure count. A new address, new events or turning it on needs the read scope of every event it then takes (403 insufficient_scope). Scope: webhooks:write.

Parameters

Request fields

Returns

The changed WebhookEndpoint:

Errors

Example

const endpoint = await admin.webhooks.get(2);
await admin.webhooks.update(
    2,
    { events: [...endpoint.events, 'order.refunded'] },
    { unmodifiedSince: endpoint.updatedAt ?? undefined },
);

Delete a webhook endpoint

admin.webhooks.delete(id: number): Promise<void>

Deletes an endpoint. Scope: webhooks:write.

Parameters

Returns

Nothing.

Errors