Skip to content
Ironflow Docs

Use Cases

Webhook 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.

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. The rest of the machinery — deduplication, retry, step memoization — is handled by Ironflow.

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. Stripe signs requests with an HMAC-SHA256 signature in the Stripe-Signature header using a v1=<hex> format.

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");


    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. Because Ironflow deduplicates by the idempotencyKey you return from transform() (here, payload.id), retries are handled automatically — the same event won’t be processed twice.

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 URL and sorted POST parameters. For simplicity, this example uses a shared auth token for HMAC verification.

1. Define the webhook:

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


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


    // Simplified HMAC verification using auth token
    const expected = crypto
      .createHmac("sha1", process.env.TWILIO_AUTH_TOKEN!)
      .update(req.body)
      .digest("base64");


    if (signature !== expected) {
      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. Using MessageSid-MessageStatus as the idempotency key ensures each unique status transition is processed exactly once — a message moving from sent to delivered creates two distinct events, but duplicate delivered callbacks are deduplicated.

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 use idempotency keys. 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 to prevent duplicate processing when providers retry.

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.