Skip to main content

Receive signed operational alerts

Partner alert delivery turns customer health and human-waiting states into a closed, machine-readable event stream. Payloads contain ids, enums, counts, timestamps, and author-controlled resource names - never exception messages or operator notes.

Verify before processing​

Signed deliveries carry:

X-Yekar-Timestamp: 1786687200
X-Yekar-Key-Id: pak_1
X-Yekar-Signature: sha256=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

The signature above is an example, not a real signature. Compute lowercase hex HMAC-SHA256 over <timestamp>.<exact raw request body> using the secret associated with X-Yekar-Key-Id, then compare in constant time. Reject stale timestamps before parsing or acting on the body.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyPartnerAlert(rawBody: Buffer, timestamp: string, signatureHeader: string, secret: string) {
  const claimed = Buffer.from(signatureHeader.replace(/^sha256=/, ""), "hex");
  const expected = Buffer.from(
    createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest("hex"),
    "hex",
  );
  return claimed.length === expected.length && timingSafeEqual(claimed, expected);
}

Delivery behavior​

Your endpoint should return a successful HTTP response only after durably accepting the event. Transient failures are retried with bounded backoff; delivery health distinguishes a retryable failure, exhausted delivery, and an undeliverable event with no live destination.

Every webhook body contains a unique deliveryId. Dedupe on that value before applying an effect. The sender suppresses terminal ledger re-entry, but a network failure after your server commits and before the response arrives can still make the remote outcome ambiguous.

Event types​

The closed event set is:

  • org.budget.threshold
  • automation.failure_rate.breached
  • automation.failure_rate.recovered
  • run.human_task.expired
  • run.gate.pending
  • run.human_task.pending
  • run.approval.pending
  • run.approval.expired
  • org.support_session.ended

Every payload carries orgId, blocking, and expiresAt. Event-specific fields add bounded facts such as threshold counts, agent or flow identity, a gate/task/tool identifier, or support-session impact counts. This no-free-text contract is a security guarantee: downstream logs and queues cannot accidentally ingest exception messages or operator-written text from the alert body.

For org.support_session.ended, use grantId with the authenticated support-session read when you need the stated reason.