Webhook Integration

FORG webhooks deliver rule trigger events, budget alerts, and anomaly notifications to any HTTP endpoint in real time. This guide covers common integration patterns.

Creating a webhook

1. Go to Dashboard → Settings → Webhooks → Add endpoint
2. Enter your endpoint URL
3. Select the event types to subscribe to
4. Copy the signing secret — you will need it to verify payloads

Verifying webhook signatures

Every webhook request includes an X-Forg-Signature header with an HMAC-SHA256 of the raw request body, signed with your webhook signing secret.

// Node.js signature verification
import crypto from "crypto";

function verifyWebhook(
  body: string,           // raw request body as string
  signature: string,      // value of X-Forg-Signature header
  secret: string          // your webhook signing secret
): boolean {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(body, "utf8")
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express handler:
app.post("/webhooks/forg", express.raw({ type: "*/*" }), (req, res) => {
  const sig = req.headers["x-forg-signature"] as string;

  if (!verifyWebhook(req.body.toString(), sig, process.env.FORG_WEBHOOK_SECRET!)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const event = JSON.parse(req.body.toString());
  handleEvent(event);
  res.status(200).end();
});

Slack integration

The simplest way to receive FORG alerts in Slack is to create an Incoming Webhook in Slack and use it as a FORG webhook endpoint:

1. In Slack, go to Apps → Incoming Webhooks → Add to Slack and create a webhook for your desired channel. Copy the Slack webhook URL.
2. In FORG, create a webhook endpoint pointing to the Slack URL.
3. Create a small relay (or use FORG's native Slack action) to format the FORG payload for Slack's Block Kit format.

For a managed Slack integration, use Dashboard → Integrations → Slack instead of a raw webhook — FORG handles formatting and OAuth automatically.

PagerDuty integration

To trigger PagerDuty incidents from FORG rule violations:

1. In PagerDuty, create a service and add an Events API v2 integration. Copy the Integration Key.
2. Create a webhook relay that transforms FORG events into PagerDuty trigger/resolve events.

// Example relay: FORG webhook → PagerDuty Events API
app.post("/relay/pagerduty", async (req, res) => {
  const event = req.body;

  // Only page on blocked events (not just notifies)
  if (event.action !== "blocked") {
    return res.status(200).end();
  }

  await fetch("https://events.pagerduty.com/v2/enqueue", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      routing_key:  process.env.PD_INTEGRATION_KEY,
      event_action: "trigger",
      payload: {
        summary:   `FORG blocked: ${event.rule_name}`,
        source:    "forg",
        severity:  "warning",
        custom_details: {
          user:    event.user_id,
          model:   event.model,
          cost:    event.cost_usd,
        },
      },
    }),
  });

  res.status(200).end();
});

Retry behavior

FORG retries failed webhook deliveries with exponential backoff: 10s, 30s, 2m, 10m, 30m, 2h, 6h. A delivery is considered failed if your endpoint returns a non-2xx status or does not respond within 10 seconds. After 7 failed attempts, the event is dropped and logged in the webhook delivery log.