Skip to main content
Get started
WebhooksRegistering endpoints
Webhooks

Registering endpoints

Connect Aly to your backend, automation tool, or queue by registering a webhook receiver.

Dashboard, REST, MCP, and CLI flows for creating webhook endpoints; rotating and deleting secrets.

Four ways to register a webhook endpoint. They all produce the same record. Use whichever fits the moment — dashboard for ad-hoc, CLI/REST/MCP for code.

Dashboard

  1. Go to Settings → Webhooks.
  2. Click New endpoint.
  3. Paste the receiving URL.
  4. Pick events. Save.
  5. Copy the signing secret — shown once.

REST

bash
curl -X POST https://aly.store/api/storefront/v1/merchant/webhooks \  -H "Authorization: Bearer aly_..." \  -H "Content-Type: application/json" \  -d '{    "url": "https://my-app.example/aly/webhooks",    "events": ["order.created", "order.fulfilled", "order.refunded"],    "site_slug": "acme",    "active": true  }'
json
{  "id": "wh_8c...",  "url": "https://my-app.example/aly/webhooks",  "events": ["order.created", "order.fulfilled", "order.refunded"],  "site_slug": "acme",  "active": true,  "secret": "whsec_8a3d...e2",  "created_at": "..."}

secret is returned exactly once. Store it server-side; it backs every signature verification.

MCP

From any MCP client (Claude Desktop, Cursor, custom):

json
{  "method": "tools/call",  "params": {    "name": "webhooks.endpoints.create",    "arguments": {      "url": "https://my-app.example/aly/webhooks",      "events": ["order.created", "order.fulfilled"],      "site_slug": "acme"    }  }}

CLI

bash
aly-store-cli webhooks create \  --site-slug acme \  --url https://my-app.example/aly/webhooks \  --event order.created \  --event order.fulfilled

Event filters

Pass an explicit list, or the wildcard "*" for every event in the catalog. We stronglyrecommend an explicit list — it's self-documenting and keeps you immune to new event types appearing in a release.

Per-site vs workspace

Include site_slug to scope an endpoint to one site. Omit it to receive events for every site in the workspace.

One endpoint per receiver
Resist the urge to point three different services at one webhook URL. Run a fan-out at your receiver instead. Aly retries per-endpoint independently; a slow consumer behind a fan-out will not retry cleanly.

Rotating secrets

bash
# RESTcurl -X POST https://aly.store/api/storefront/v1/merchant/webhooks/wh_8c.../rotate-secret \  -H "Authorization: Bearer aly_..."

Returns a new secret. The old one is invalidated immediately — make sure your receiver accepts both during the deploy window if you can't do a synchronous swap.

Disabling and deleting

PATCH with active: false to pause delivery (events are dropped, not queued). DELETE for permanent removal — past deliveries remain visible in the audit log for the retention window.

Updated

Was this page helpful?