Guide: Webhooks + Settlement Automation

Goal

This guide wires deterministic outcomes into your internal systems so approvals, holds, and disputes trigger downstream actions automatically.

1. Register webhook endpoints

POST /v1/webhooks
{
  "url": "https://your-app.com/webhooks/settld",
  "events": [
    "run.finalized",
    "settlement.completed",
    "settlement.held",
    "dispute.opened"
  ]
}

2. Verify signatures on every event

Never trust unsigned payloads. Validate the signature header before parsing event data, then process idempotently using the event ID.

3. Map events to business actions

export async function POST(req: Request) {
  const signature = req.headers.get("settld-signature");
  const payload = await req.text();
  verifySignature(payload, signature);

  const event = JSON.parse(payload);
  switch (event.type) {
    case "settlement.completed":
      await markInvoicePaid(event.data.runId, event.data.amount);
      break;
    case "settlement.held":
      await openExceptionQueue(event.data.runId);
      break;
    case "dispute.opened":
      await notifyOps(event.data.disputeId);
      break;
  }

  return new Response(null, { status: 204 });
}

Recommended event handling matrix

• run.finalized: store artifact metadata and status snapshot.
• settlement.completed: close invoice and release payout.
• settlement.held: route to exception queue with context.
• dispute.opened: open case workflow and notify ops.