Webhooks

Subscribe a URL to what happens in a store; the Gateway POSTs a signed payload when it happens. No public URL? Pull the same events with GET /events (MCP: dtc_list_events).

curl -X POST https://api.platformdtc.com/api/v1/agent/v1/webhooks \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://your.app/hooks/dtc","events":["order.paid","inventory.low"],
       "approval_context":{"merchant_confirmed":true}}'
# -> { "data": { "id":"…", "secret":"<shown once>" } }

MCP: dtc_create_webhook, dtc_list_webhooks, dtc_delete_webhook. The URL must be a public https:// address. A webhook is a standing channel that receives store data, so:

creating one needs store:write and the read permission of every event you subscribe to (the table below): a connection never receives what it could not read with its own tools;
an agent key must send approval_context {"merchant_confirmed": true} after the store owner agreed to the URL and the events — without it the call answers status: "pending_approval" and creates nothing;
the signing secret is returned once — store it.

Listing needs store:read; deleting needs store:write. An operator key with agent:admin can do all three.

Events

Event	Fires when	Needs
`order.created`	a new order comes in	`orders:read`
`order.paid`	an order is paid	`orders:read`
`order.refunded`	an order is refunded	`orders:read`
`order.fulfilled`	an order is shipped	`orders:read`
`checkout.abandoned`	a shopper leaves checkout without buying	`checkout:read`
`inventory.low`	a tracked product’s stock drops to its low-stock line (5 unless the store or the product sets one: `dtc_set_low_stock_alert`); at most once per product per day	`read_inventory`
`customer.created`	a new customer signs up or buys	`customers:read`
`subscription.cancelled`	a subscription is cancelled	`orders:read`
`review.created`	a customer leaves a product review	`catalog:read`
`return.requested`	a customer asks to return or exchange items on the store	`read_returns`
`ticket.created`	a customer writes to support	`read_support`
`approval.requested`	an agent’s action waits for the owner’s OK	`store:read`
`approval.resolved`	the owner approves or declines it	`store:read`
`job.completed` / `job.failed`	an async job succeeds / fails	`store:read`
`deploy.ready` / `deploy.failed`	a publish goes live / fails	`store:read`
`theme.published` / `theme.publish_failed`	a theme publish requested through the theme API went live / failed (the previous theme stays live)	`store:read`
`roas.threshold`	ROAS crosses a configured threshold	`store:read`

Store events (the first twelve) carry event_id, store_id, occurred_at and the ids and numbers you need to fetch the details with the matching tool (for example order_id, order_number, total_cents, currency; money is in cents). Delivery is at least once: deduplicate on data.event_id.

Pull instead of push

curl -s "https://api.platformdtc.com/api/v1/agent/v1/events?types=order.paid,inventory.low&limit=50" \
  -H "Authorization: Bearer $KEY"
# -> { "data": { "items": [ … oldest first … ], "next_cursor": "…", "has_more": false } }

Call again with after=<next_cursor> to get only newer events. Results are limited to the events your connection may read. Events are kept for 30 days.

Delivery format

POST /hooks/dtc
X-Webhook-Event: job.completed
X-Webhook-Id: <subscription id>
X-Webhook-Signature: sha256=<hex>
Content-Type: application/json

{ "event": "job.completed", "data": { "job_id": "…", "status": "succeeded", … }, "webhook_id": "…" }

Verify the signature

The signature is HMAC-SHA256(secret, raw_body). Compare in constant time:

import hmac, hashlib

def verify(secret: str, raw_body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

import crypto from "node:crypto";

export function verify(secret, rawBody, header) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

Verify against the raw request body (not a re-serialized object), and reject on mismatch. Deliveries retry with backoff on non-2xx responses.

Reference

Endpoints

Events

Pull instead of push

Delivery format

Verify the signature

​Subscribe

​Events

​Pull instead of push

​Delivery format

​Verify the signature

Subscribe

Events

Pull instead of push

Delivery format

Verify the signature