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 Webhooks::verifySignature.

List webhook endpoints

$admin->webhooks->list(array $query = []): array

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

An array with data (a list of WebhookEndpoint), links and meta:

Errors

Example

$page = $admin->webhooks->list();
$endpoints = $page['data'];

Iterate over every endpoint

$admin->webhooks->all(array $query = []): Generator

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

A generator of WebhookEndpoint arrays, each:

Example

foreach ($admin->webhooks->all() as $endpoint) {
    if (! $endpoint['active']) {
        $admin->webhooks->update($endpoint['id'], ['active' => true]);
    }
}

Get a webhook endpoint

$admin->webhooks->get(int $id): array

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

Parameters

Returns

A WebhookEndpoint:

Errors

Add a webhook endpoint

$admin->webhooks->create(array $input, string|false|null $idempotencyKey = null): array

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 array: the endpoint in data, and its secret:

Errors

Example

$created = $admin->webhooks->create([
    'url' => 'https://erp.example.com/storehugs/webhooks',
    'events' => ['order.created', 'order.status_changed', 'product.stock_changed'],
]);
$secret = $created['secret']; // Keep it to verify deliveries.

Update a webhook endpoint

$admin->webhooks->update(
    int $id,
    array $changes,
    DateTimeInterface|string|null $unmodifiedSince = null,
    string|false|null $idempotencyKey = null,
): array

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

$endpoint = $admin->webhooks->get(2);
$admin->webhooks->update(2, [
    'events' => [...$endpoint['events'], 'order.refunded'],
], unmodifiedSince: $endpoint['updatedAt']);

Delete a webhook endpoint

$admin->webhooks->delete(int $id): void

Deletes an endpoint. Scope: webhooks:write.

Parameters

Returns

Nothing.

Errors