Webhooks - PlatformDTC

Subscribe a URL to platform events; the Gateway POSTs a signed payload when they occur.

curl -X POST https://api.platformdtc.com/api/v1/agent/v1/webhooks \
  -H "X-Agent-Key: sq_agt_admin" -H "Content-Type: application/json" \
  -d '{"url":"https://your.app/hooks/dtc","events":["job.completed","deploy.ready"]}'
# -> { "data": { "id":"…", "secret":"<shown once>" } }

Requires agent:admin. The signing secret is returned once — store it. Manage with GET /webhooks and DELETE /webhooks/{id}.

Events

Event	Fires when
`job.completed`	an async job succeeds
`job.failed`	an async job fails
`deploy.ready`	a publish goes live
`deploy.failed`	a publish fails
`order.created`	a new order is placed
`roas.threshold`	ROAS crosses a configured threshold
`approval.requested`	a spend action awaits human approval

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.