Skip to content
ironflow

Use Cases

This page walks through complete webhook integrations for three common providers. Each example shows the full flow: webhook definition with signature verification, an event-handling function, and serve wiring.

These examples use the SDK path

Every integration below uses createWebhook() — your app receives the request, verifies it, and forwards an event to Ironflow. You own the verification code, which is why these examples spell it out in full.

The server-side path (registering a source and pointing the provider at /api/v1/webhooks/{id}) verifies signatures itself, using a generic signature descriptor (ADR 0049) whose signing_template covers Stripe’s <timestamp>.<body> as well as GitHub’s bare body. It does not cover Twilio (which signs the request URL plus sorted parameters), so Twilio must use the SDK path shown here. See Setup for the server-side path.

The Pattern

Every webhook integration follows the same three steps:

1. Define webhook    →  verify signature + transform payload into an Ironflow event
2. Write function    →  handle the event with durable steps
3. Wire it up        →  pass both to serve() or register via CLI

The webhook definition is the only part that changes between providers. Once the event is emitted, Ironflow handles run retries and step memoization.

idempotencyKey is honored on this path

Both SDKs forward transformed events through IronflowService/Emit, including the idempotencyKey returned by transform(). Use a stable provider event ID so repeated deliveries deduplicate. Server-managed sources use their configured dedup_id_path.

Note what this does not cover: Ironflow does not retry or replay the provider’s HTTP delivery itself. If your endpoint is down when Stripe posts, recovery is Stripe’s retry schedule, not Ironflow’s — so return quickly and let the durable function do the slow work.

Stripe: Payment Processing

Stripe sends webhook events for payment lifecycle changes. The most common use case is fulfilling orders when a payment succeeds.

What Stripe sends: JSON payload with a type field (e.g., payment_intent.succeeded), a top-level id for deduplication, and a data.object containing the resource.

The Stripe-Signature header is a comma-separated list — t=<unix-timestamp>,v1=<hex>,v0=<hex> — and the HMAC-SHA256 is computed over <timestamp>.<raw-body>, not over the body alone. Verify the v1 scheme only; v0 is a test-only signature and honoring it enables a downgrade attack. Because the timestamp is inside the signed payload, an attacker cannot alter it without breaking the signature, which is what makes the freshness check below meaningful.

1. Define the webhook:

import { createWebhook } from "@ironflow/node";
import crypto from "crypto";


const stripeWebhook = createWebhook({
  id: "stripe",
  verify: (req) => {
    const header = req.headers["stripe-signature"];
    if (!header) throw new Error("Missing Stripe-Signature header");


    // Stripe header format: t=<timestamp>,v1=<hex>,v0=<hex>
    const parts: Record<string, string> = {};
    for (const segment of header.split(",")) {
      const [k, v] = segment.split("=");
      if (k && v) parts[k] = v;
    }
    if (!parts.t || !parts.v1) throw new Error("Malformed Stripe signature");


    // Reject stale deliveries. Without this the signature stays valid forever,
    // so a captured request can be replayed indefinitely. Stripe's own
    // libraries default to a 5-minute tolerance; never use 0, which disables
    // the check entirely.
    const ageSeconds = Math.abs(Date.now() / 1000 - Number(parts.t));
    if (!Number.isFinite(ageSeconds) || ageSeconds > 300) {
      throw new Error("Stripe signature timestamp outside tolerance");
    }


    const signed = `${parts.t}.${req.body}`;
    const expected = crypto
      .createHmac("sha256", process.env.STRIPE_WEBHOOK_SECRET!)
      .update(signed)
      .digest("hex");


    const a = Buffer.from(parts.v1, "hex");
    const b = Buffer.from(expected, "hex");
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      throw new Error("Invalid signature");
    }
  },
  transform: (payload: any) => ({
    name: `stripe.${payload.type}`,
    data: payload.data.object,
    idempotencyKey: payload.id,
  }),
});

2. Write the function:

import { createFunction } from "@ironflow/node";


const fulfillOrder = createFunction(
  {
    id: "fulfill-order",
    triggers: [{ event: "stripe.payment_intent.succeeded" }],
  },
  async ({ event, step }) => {
    const payment = event.data as {
      id: string;
      amount: number;
      currency: string;
      metadata: { orderId: string };
    };


    await step.run("update-order-status", async () => {
      // Mark the order as paid in your database
      return { orderId: payment.metadata.orderId, status: "paid" };
    });


    await step.run("send-confirmation", async () => {
      // Send a confirmation email to the customer
      return { sent: true };
    });


    return { fulfilled: true, orderId: payment.metadata.orderId };
  },
);

3. Wire it up:

import { serve } from "@ironflow/node";


export default serve({
  functions: [fulfillOrder],
  webhooks: [stripeWebhook],
  serverUrl: process.env.IRONFLOW_URL,
});

Stripe tip

Stripe retries failed webhook deliveries for up to 3 days. The idempotencyKey you return from transform() (here, payload.id) is forwarded to Emit, which returns the existing event instead of creating a second one — so a retry does not re-run the function. Dedup is environment-scoped: the same key in a different environment is a different event.

Production verification

The hand-rolled verifier above is shown for clarity. For production, prefer Stripe’s official library: stripe.webhooks.constructEvent(req.body, header, secret). It performs the same t=...,v1=... parse, timestamp tolerance check, and timing-safe compare in one call.

GitHub: Repository Automation

GitHub sends webhook events for repository activity. Common use cases include triggering deployments on push, running checks on pull requests, and syncing issue trackers.

What GitHub sends: JSON payload with the event type in the X-GitHub-Event header (not in the body). The delivery ID is in X-GitHub-Delivery. GitHub signs requests with HMAC-SHA256 in the X-Hub-Signature-256 header using a sha256=<hex> format.

1. Define the webhook:

import { createWebhook } from "@ironflow/node";
import crypto from "crypto";


const githubWebhook = createWebhook({
  id: "github",
  verify: (req) => {
    const signature = req.headers["x-hub-signature-256"];
    if (!signature) throw new Error("Missing X-Hub-Signature-256 header");


    const expected =
      "sha256=" +
      crypto
        .createHmac("sha256", process.env.GITHUB_WEBHOOK_SECRET!)
        .update(req.body)
        .digest("hex");


    const a = Buffer.from(signature);
    const b = Buffer.from(expected);
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      throw new Error("Invalid signature");
    }
  },
  transform: (payload: any) => ({
    // GitHub puts the event type in the X-GitHub-Event header (not in the
    // payload), and `action` further qualifies it (e.g. opened/closed for
    // pull_request). The SDK's transform() only sees the parsed payload, so
    // we name events off `action` here — set `event_prefix=github` and rely
    // on payload `action` where present.
    name: `github.${payload.action || "event"}`,
    data: payload,
    // The unique delivery ID lives in the X-GitHub-Delivery header, which
    // transform() cannot see. For push events the head commit SHA is a
    // reasonable per-delivery key; pick a payload field that is stable per
    // delivery for the event types you handle.
    idempotencyKey:
      payload.head_commit?.id ??
      payload.pull_request?.id?.toString() ??
      payload.issue?.id?.toString(),
  }),
});

2. Write the function:

import { createFunction } from "@ironflow/node";


const deployOnPush = createFunction(
  {
    id: "deploy-on-push",
    triggers: [{ event: "github.push" }],
  },
  async ({ event, step }) => {
    const push = event.data as {
      ref: string;
      repository: { full_name: string };
      head_commit: { id: string; message: string };
    };


    // Only deploy from main branch
    if (push.ref !== "refs/heads/main") {
      return { skipped: true, reason: "not main branch" };
    }


    const buildResult = await step.run("build", async () => {
      // Trigger your build pipeline
      return { buildId: `build-${push.head_commit.id.slice(0, 7)}` };
    });


    await step.run("deploy", async () => {
      // Deploy the build
      return { deployed: true, buildId: buildResult.buildId };
    });


    await step.run("notify-slack", async () => {
      // Notify the team
      return { notified: true };
    });


    return { deployed: true, commit: push.head_commit.id };
  },
);

3. Wire it up:

import { serve } from "@ironflow/node";


export default serve({
  functions: [deployOnPush],
  webhooks: [githubWebhook],
  serverUrl: process.env.IRONFLOW_URL,
});

GitHub event types & idempotency

GitHub puts the event type in the X-GitHub-Event header and the per-delivery UUID in X-GitHub-Delivery — neither is in the payload body. The current SDK only passes the parsed payload to transform(), so the example uses payload.action for naming and a payload-derived key (head_commit.id, pull_request.id, issue.id) for idempotency. If you need the GitHub delivery UUID, mount your own route around createWebhook and inject it before calling Ironflow, or rely on the event-type-specific keys shown.

Twilio: SMS and Communications

Twilio sends status callbacks when message delivery states change. Common use cases include tracking delivery receipts, handling inbound messages, and updating communication logs.

What Twilio sends: Form-encoded or JSON payload with fields like MessageSid, MessageStatus, and To. Twilio authenticates requests using a signature in the X-Twilio-Signature header computed over the full request URL plus the POST parameters sorted alphabetically — not over the raw body.

That last point matters: unlike Stripe and GitHub, a Twilio signature cannot be checked from the body alone, because the URL is part of the signed material. This is deliberate — it stops an attacker replaying a valid request against a different endpoint. It also means you must pass the exact public URL Twilio called, including query string; behind a proxy that rewrites the host or scheme, reconstructing it from the inbound request will silently fail verification.

Use Twilio’s own validator rather than hand-rolling the canonicalization.

1. Define the webhook:

import { createWebhook } from "@ironflow/node";
import twilio from "twilio";


const twilioWebhook = createWebhook({
  id: "twilio",
  verify: (req) => {
    const signature = req.headers["x-twilio-signature"];
    if (!signature) throw new Error("Missing X-Twilio-Signature header");


    // Must be the exact public URL Twilio called, including query string.
    const url = process.env.TWILIO_WEBHOOK_URL!;
    const params = Object.fromEntries(new URLSearchParams(req.body));


    // validateRequest handles the canonicalization (URL + alphabetically
    // sorted params) and the constant-time comparison.
    if (!twilio.validateRequest(process.env.TWILIO_AUTH_TOKEN!, signature, url, params)) {
      throw new Error("Invalid Twilio signature");
    }
  },
  transform: (payload: any) => ({
    name: `twilio.${(payload.MessageStatus || payload.EventType || "message").toLowerCase()}`,
    data: {
      messageSid: payload.MessageSid,
      from: payload.From,
      to: payload.To,
      body: payload.Body,
      status: payload.MessageStatus,
    },
    idempotencyKey: payload.MessageSid
      ? `${payload.MessageSid}-${payload.MessageStatus}`
      : undefined,
  }),
});

2. Write the function:

import { createFunction } from "@ironflow/node";


const handleSmsStatus = createFunction(
  {
    id: "handle-sms-status",
    triggers: [
      { event: "twilio.delivered" },
      { event: "twilio.failed" },
      { event: "twilio.undelivered" },
    ],
  },
  async ({ event, step }) => {
    const sms = event.data as {
      messageSid: string;
      to: string;
      status: string;
    };


    await step.run("update-message-log", async () => {
      // Update the message status in your database
      return { messageSid: sms.messageSid, status: sms.status };
    });


    if (sms.status === "failed" || sms.status === "undelivered") {
      await step.run("alert-on-failure", async () => {
        // Notify support about the failed delivery
        return { alerted: true, to: sms.to };
      });
    }


    return { processed: true, messageSid: sms.messageSid };
  },
);

3. Wire it up:

import { serve } from "@ironflow/node";


export default serve({
  functions: [handleSmsStatus],
  webhooks: [twilioWebhook],
  serverUrl: process.env.IRONFLOW_URL,
});

Twilio idempotency

Twilio can send the same status callback multiple times, and MessageSid-MessageStatus is the right key to carry — a message moving from sent to delivered is two distinct transitions, while a repeated delivered callback is one. Emit dedups on it, so a repeated delivered callback resolves to the same event and does not start a second run.

Twilio body format

Twilio status callbacks default to application/x-www-form-urlencoded. The Node SDK calls JSON.parse(body) before invoking transform(), so form-encoded payloads will fail with TRANSFORM_FAILED. Either configure your Twilio webhook to send JSON in the Twilio console, or front the SDK with a small adapter route that re-encodes form bodies as JSON. The Go example above handles both via url.ParseQuery fallback because Go’s Transform receives raw bytes.

Common Patterns

These patterns apply across all webhook integrations:

Always carry the provider’s event ID. Most providers include a unique event ID in their payloads (id for Stripe, X-GitHub-Delivery for GitHub, MessageSid for Twilio). Return it from transform() as idempotencyKey — on the SDK path Emit dedups on it, and a server-managed source (Path A) dedups on its configured dedup_id_path. Dedup is environment-scoped, and it only collapses duplicate events; a step with a side effect still needs step.run so it is memoized across retries of the same run.

Namespace events by provider. Use a consistent prefix like stripe., github., twilio. so you can write targeted function triggers and avoid event name collisions across providers.

Keep verify and transform simple. The verify() function should only validate the signature — don’t make external API calls. The transform() function should extract and reshape the payload — don’t perform business logic. Business logic belongs in the function handler where it benefits from durable steps and retry.

Handle multiple event types. A single webhook source often sends many event types. Write separate functions for each type you care about rather than one function with a giant switch statement:

// Good: separate functions per event type
const onPaymentSucceeded = createFunction({
  id: "on-payment-succeeded",
  triggers: [{ event: "stripe.payment_intent.succeeded" }],
}, async ({ event, step }) => { /* ... */ });


const onPaymentFailed = createFunction({
  id: "on-payment-failed",
  triggers: [{ event: "stripe.payment_intent.payment_failed" }],
}, async ({ event, step }) => { /* ... */ });

Monitoring with the Dashboard

Once webhooks are flowing, the Ironflow dashboard gives you visibility into every provider without touching code or the CLI.

Webhooks page — lists all registered webhook sources. You can create new sources directly from the UI by filling in the provider ID, event prefix, and optional signature verification settings. This is useful for adding a provider quickly in development or for ops teams that manage sources without deploying code changes.

Webhook Deliveries page — shows every incoming webhook delivery for a given source. Each row displays the status (accepted, deduplicated, rejected, failed), external ID, timestamp, and linked event ID. You can:

  • Filter by status to find failures — e.g., show only rejected deliveries to diagnose signature verification issues with a new provider
  • Expand a delivery to inspect the full request headers and body — useful for debugging transform logic or understanding exactly what a provider sent
  • Cross-reference events — click through from a delivery to the event it created, then to the function runs it triggered

Typical debugging workflow: When a webhook integration isn’t working as expected, open the Deliveries page filtered to the provider. If deliveries show rejected, the signature verification is failing — check the secret. If deliveries show accepted but no runs are triggered, the event name doesn’t match any function trigger — check the event prefix and payload type field. The raw payload in the delivery detail view shows exactly what the provider sent, so you can verify your transform() logic against real data.