Webhooks (API Client)

Manage webhook subscriptions programmatically using client.webhooks — list, create, update, and delete webhook registrations.

client.webhooks lets your plugin manage webhook subscriptions for a merchant's store via the REST API. This is the programmatic alternative to declaring webhooks statically in your whatalo.app.ts manifest.

For receiving and verifying webhook payloads, see the Webhooks section.

Required Scopes

Operation	Required Scope
`list`	`read:webhooks`
`create`, `update`, `delete`	`write:webhooks`

HTTP Mapping

Method	HTTP Verb	Path
`list()`	GET	`/webhooks`
`create(data)`	POST	`/webhooks`
`update(id, data)`	PATCH	`/webhooks/:id`
`delete(id)`	DELETE	`/webhooks/:id`

Methods

list

Retrieve all webhook subscriptions registered for the store.

const webhooks = await client.webhooks.list();

webhooks.forEach((wh) => {
  console.log(`${wh.id}: ${wh.url} — events: ${wh.events.join(", ")}`);
});

create

const webhook = await client.webhooks.create({
  url: "https://my-plugin.com/api/webhooks",
  events: ["order.created", "product.updated"],
  secret: "my-signing-secret", // Used to verify HMAC signatures
});

console.log(webhook.id); // Store this ID to update or delete later

update

Update the event subscriptions for an existing webhook.

await client.webhooks.update("wh_123", {
  events: ["order.created", "order.updated", "order.cancelled"],
});

delete

Remove a webhook subscription. The endpoint will stop receiving events immediately.

await client.webhooks.delete("wh_123");

Manifest vs. API Registration

Webhooks can be declared in two ways:

Approach	When to use
`whatalo.app.ts` manifest (`webhooks` field)	Simple, static event lists known at deploy time
`client.webhooks.create` (API)	Dynamic subscriptions that depend on merchant settings or plan

For most plugins, the manifest approach is simpler. Use the API approach when merchants need to choose which events to subscribe to from within your plugin's own settings UI.

Error Handling

import { ValidationError, AuthorizationError } from "@whatalo/plugin-sdk";

try {
  await client.webhooks.create({
    url: "not-a-valid-url",
    events: ["order.created"],
    secret: "my-secret",
  });
} catch (error) {
  if (error instanceof ValidationError) {
    error.fieldErrors.forEach((e) => console.log(`${e.field}: ${e.message}`));
  } else if (error instanceof AuthorizationError) {
    console.log(`Missing scope: ${error.requiredScope}`);
  } else {
    throw error;
  }
}

See Errors & Rate Limits for the full error class reference.

On this page