Webhooks API

This page specifies a proposed webhook contract. No public v1.0 webhook-management service, delivery latency, retry schedule, or retention commitment exists today. The endpoints, signatures, and timelines below are reference examples.

Shared conventions, including authentication, pagination, the Idempotency-Key header, and the error envelope, are defined in the API overview. Error codes are catalogued in Errors.

#Subscription event types

An endpoint subscribes to one or more delivery types. Each delivery wraps the full current API object named in the table, so a consumer needs no follow-up fetch for the common cases.

Types follow the API's noun.verb convention, and new types are additive within the major version; ignore types you do not recognize.

#The webhook endpoint object

curl -X POST https://api.fibric.io/v1/webhook_endpoints \
  -H "Authorization: Bearer $FIBRIC_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: whk-create-ops-consumer" \
  -d '{
    "url": "https://ops.example.com/fibric/webhook",
    "types": ["plan.proposed", "action.needs_approval", "connector.status_changed"]
  }'

{
  "id": "whk_6b3e0d",
  "object": "webhook_endpoint",
  "url": "https://ops.example.com/fibric/webhook",
  "types": ["plan.proposed", "action.needs_approval", "connector.status_changed"],
  "status": "active",
  "secret": "whsec_5f2e8a1c9b0d7e4f6a3b",
  "created_at": "2026-07-02T15:30:00Z",
  "last_delivery_at": null
}

Error cases:

Returns the tenant's endpoints, newest first, cursor-paginated with the standard limit and cursor parameters. The secret reads as a hint.

The target update operation changes endpoint configuration and can rotate a signing secret with a managed overlap window. No public endpoint or standard overlap duration exists today.

curl -X PATCH https://api.fibric.io/v1/webhook_endpoints/whk_6b3e0d \
  -H "Authorization: Bearer $FIBRIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rotate_secret": true}'

Deletes the endpoint. Pending retries for it are dropped; delivery records remain readable for their retention window.

#The delivery object

Every attempt to reach your endpoint is recorded as a delivery. The same shape is what arrives in the HTTP POST body.

POST /fibric/webhook HTTP/1.1
Content-Type: application/json
Fibric-Signature: t=1782064081,v1=6e8a2c91f0b34d7e5a1c9f82d4b60e3a7c5f9b1d8e2a4c6f0b3d5e7a9c1f4b68

{
  "id": "dlv_9c4f2e",
  "object": "webhook_delivery",
  "endpoint_id": "whk_6b3e0d",
  "type": "action.needs_approval",
  "correlation_id": "co_51d2e8",
  "attempt": 1,
  "created_at": "2026-07-02T15:02:10Z",
  "data": {
    "id": "act_91d1",
    "object": "action",
    "plan_id": "pl_7c1a",
    "tool": "order.notify",
    "entity_key": "order:SO-10884",
    "disposition": "ALERT"
  }
}

The proposed endpoint returns cursor-paginated delivery records and illustrates redelivery. Retention is deployment-specific; no public 30-day commitment or callable replay endpoint exists.

#Retries and backoff

The table below is a reference retry profile, not a current service commitment. Managed deployments define response deadlines, attempts, backoff, retention, and suspension behavior in writing:

Jitter, failure state, notification, suspension, and redelivery are target behaviors. They are not a public SLO or retention promise.

#Verifying Fibric-Signature

Every delivery carries a Fibric-Signature header: a Unix timestamp and one or more HMAC-SHA256 signatures, hex-encoded.

Fibric-Signature: t=1782064081,v1=6e8a2c91f0b34d7e5a1c9f82d4b60e3a7c5f9b1d8e2a4c6f0b3d5e7a9c1f4b68

The signed message is the timestamp, a period, and the raw request body: {t}.{body}. To verify: compute HMAC-SHA256 over that message with your whsec_ secret, compare in constant time against each v1 value (two are present during a secret rotation), and reject if the timestamp is older than your tolerance, five minutes is conventional, to defeat replay.

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

function verifyFibricSignature(header: string, rawBody: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // 5-minute tolerance

  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  const given = Buffer.from(String(parts.v1 ?? ""), "hex");
  const want = Buffer.from(expected, "hex");
  return given.length === want.length && timingSafeEqual(given, want);
}

Verify against the raw body bytes, before any JSON parsing or re-serialization; a re-stringified body will not match. Respond 2xx quickly and do the work asynchronously: the 10-second window includes your processing time.

#Errors