Webhooks & Event-Driven Automation

Webhooks and event-driven automation are the trigger side of the workflow — the systems POST events to your endpoint (L220), the endpoint verifies the signature (L212), validates the event contract (L163), and hands off to the queue (L222) — with idempotency (L255) for the at-least-once delivery and a failure story (L232), because events are how the business talks to the automation (L230).

The one-sentence interview answer: "Webhooks are how the business triggers the automation (L220). The system — a CRM (L223), an inbox (L224), a payment provider (L227) — POSTs an event to my endpoint: 'a lead was created', 'a payment succeeded'. The endpoint does four things (L220). Verify — the signature proves the event is from the system, not an attacker (L212). Validate — the event matches its contract (L163): the fields, the shape (L143). Idempotency — delivery is at-least-once (L255): the same event can arrive twice, so the handler keys on the event ID and deduplicates (L255). Hand off — the endpoint enqueues the work (L222) and returns 200 fast; the worker (L222) runs the workflow (L217). The failure story: retries (L169), dead letters (L232), and the at-least-once semantics (L255) — the event path is designed, not hoped for (L230)."

Think of the webhook as the mail slot of the automation house. The outside systems are the senders: the CRM mails "a lead was created" (L223), the payment provider mails "a payment succeeded" (L227). The mail slot is your webhook endpoint (L220) — the only opening, and it's checked: the envelope's seal is verified (the signature, L212), the letter is read (the event contract, L163), and the letter's ID is logged against the duplicates (idempotency, L255) — the same letter arriving twice doesn't get two replies (L255). Then the letter is dropped into the in-tray (the queue, L222), and the workers (L222) do the work. The house works because the slot is guarded, the letters are deduplicated, and the in-tray never overflows (L230).

   the senders (L223-227)          the mail slot (the webhook, L220)
   ┌────────────────────┐          ┌────────────────────────────────┐
   │ CRM: lead created  │ ──────►  │ verify the seal (L212)         │
   │ email: received    │          │ read the letter (L163)         │
   │ payment: succeeded │          │ dedupe by the ID (L255)        │
   └────────────────────┘          │ drop in the in-tray (L222)     │
                                   └────────────────────────────────┘

The mental model is the guarded mail slot: verified, deduplicated, and handed to the in-tray — events in, work queued (L220).

   a system emits an event (L223-227)
        │
        ▼
   ┌──────────────────────────────────────────────────────────┐
   │ 1 · THE WEBHOOK (L220)                                   │
   │     the system POSTs to the endpoint                     │
   └──────────────────┬───────────────────────────────────────┘
                      ▼
   ┌──────────────────────────────────────────────────────────┐
   │ 2 · VERIFY (L212)                                        │
   │     the signature — is it really from the system?        │
   │     reject the forged and the unknown (L212)             │
   └──────────────────┬───────────────────────────────────────┘
                      ▼
   ┌──────────────────────────────────────────────────────────┐
   │ 3 · VALIDATE + DEDUPE (L163, L255)                       │
   │     the event matches its contract (L143)                │
   │     the ID is new? → proceed · seen? → 200, done (L255)  │
   └──────────────────┬───────────────────────────────────────┘
                      ▼
   ┌──────────────────────────────────────────────────────────┐
   │ 4 · HAND OFF (L222)                                      │
   │     enqueue the event → 200 to the system (fast)         │
   │     the worker runs the workflow (L217)                  │
   └──────────────────────────────────────────────────────────┘

The flow is the event path: verify → validate + dedupe → hand off — the guarded slot that turns an event into a workflow run (L220).

• The webhook (L220). The system POSTs an event to your endpoint (L220): a CRM lead (L223), an email (L224), a payment (L227). The endpoint is the trigger node of the L217 workflow (L220).
• The verification (L212). The signature — HMAC or a similar shared-secret scheme (L212) — proves the event came from the system (L220). The endpoint rejects the unsigned and the forged (L212). Verification is the webhook's security (L212).
• The contract (L163, L143). The event is a defined shape: the fields, the types, the required ones (L143). The endpoint validates before processing (L163) — a malformed event is rejected, not processed (L220).
• The delivery (L255). Webhook delivery is at-least-once (L255): the system retries on failures, so the same event can arrive twice (L232). The handler keys on the event ID and deduplicates (L255) — idempotency is the event path's requirement (L220).
• The handoff (L222). The endpoint enqueues the event (L222) and returns 200 fast (L151) — the worker (L222) runs the workflow (L217). The endpoint is the door; the queue is the in-tray (L222).

• CRM events (L223). A lead is created → the webhook (L220) → the enrichment workflow (L217) runs (L223).
• Payment events (L227). A payment succeeds → the webhook (L220) → the fulfillment workflow (L217) — with the signature verified (L212) and the ID deduplicated (L255).
• Email events (L224). An email arrives → the webhook (L220) → the triage workflow (L224).
• Support events. A ticket is created → the webhook (L220) → the triage + draft workflow (L217).
• Anything the business emits (L230). The event path is the trigger side of the L230 platform — webhooks in, queues, workflows (L230).

The through-line: the webhook is how the business talks to the automation — the guarded, deduplicated mail slot that starts the workflows (L220).

Say it in four moves:

1. The trigger. "The systems POST events to my endpoint (L220) — a lead, an email, a payment (L223–227)."
2. The guard. "Verify the signature (L212), validate the contract (L163), dedupe by the event ID (L255)."
3. The handoff. "Enqueue (L222) and return 200 fast — the worker runs the workflow (L217)."
4. The semantics. "Delivery is at-least-once (L255) — the handler is idempotent, and the failures (L232) are designed."

• The event path is the platform's front door (L230). The senior answer designs the webhook (L220), the queue (L222), and the workflow (L217) as one path (L230) — the endpoint is the door, not a script (L220).
• Verification is the security baseline (L212). The signature check (L212) is what makes the endpoint safe to expose (L220) — a forged event is an injection into the automation (L212).
• Idempotency is the delivery semantics' consequence (L255). At-least-once (L255) is the provider's contract; idempotency is the handler's response (L220) — the senior answer names both halves (L255).
• The endpoint is the fast path (L151). Verify, validate, dedupe, enqueue — then 200 (L151). The heavy work (L217) is the worker's (L222), never the endpoint's (L220).
• The failures are designed (L232). Retries (L169), dead letters (L232), and the replay story (L255) — the event path's recovery is part of the design (L230).

• An unverified endpoint (L212). Any POST starts the workflow (L220) — the forged-event injection (L212).
• Non-idempotent handling (L255). The duplicate event double-processes (L255) — double refunds, double writes (L232).
• The heavy work in the endpoint (L151). The workflow runs inside the request (L222) — slow responses (L151) and the provider's retries (L232).
• No event contract (L163). The malformed event processed blindly (L143) — the workflow receives garbage (L220).
• No failure story (L232). A failed event dropped (L232) — no retry (L169), no dead letter (L222).
• The webhook as a script (L230). The endpoint starting one script instead of the platform's path (L222) — the L230 design skipped (L230).

• Verify the signature first (L212) — HMAC or the provider's scheme (L220).
• Define the event contract (L163, L143) — the shape, the required fields (L220).
• Dedupe by the event ID (L255) — the at-least-once response (L232).
• Enqueue and return 200 fast (L222, L151) — the worker runs the workflow (L217).
• Design the failure story (L232) — retries (L169), dead letters (L222).
• Log the event path (L213) — the trigger's trace (L341).

Q: How do you trigger AI work from your systems?

A: Webhooks (L220). The systems — a CRM (L223), an inbox (L224), a payment provider (L227) — POST events to my endpoint: "a lead was created". The endpoint verifies the signature (L212), validates the event contract (L163), dedupes by the event ID (L255), and enqueues the work (L222) — returning 200 fast (L151). The worker (L222) runs the workflow (L217).

Q: Why is the webhook idempotent?

A: Because delivery is at-least-once (L255). Webhook providers retry undelivered events (L232) — the same event can arrive twice. A non-idempotent handler double-processes: double refunds, double CRM writes (L255). So the handler keys on the event ID: the first arrival processes, the duplicate returns 200 without work (L220). Idempotency is the delivery semantics' requirement (L255).

Q: How do you secure the webhook?

A: The signature (L212). The provider signs the request — HMAC with a shared secret (L212) — and the endpoint verifies it before anything else (L220). The unsigned and the forged are rejected (L212). Without it, anyone can POST a forged event and start the automation — an injection into the platform (L212, L220).

Q: Why doesn't the endpoint do the work?

A: The endpoint is the door, not the worker (L222). If the workflow runs inside the request, the response is slow (L151) and the provider retries (L232). The endpoint verifies, validates, dedupes, and enqueues — then returns 200 (L220). The worker (L222) picks up the event and runs the workflow (L217) — the heavy work is off the event path (L222).

• How does signature verification work (L212)?
• What's the at-least-once semantics (L255)?
• How does the queue handoff work (L222)?
• What's in the event contract (L163)?
• How does the failure story look (L232)?

The senior read: the right column is the platform's front door — verified, deduplicated, and handed to the queue (L230).

// The webhook: verify → validate + dedupe → hand off (L220).
export async function POST(req) {
  // 1 · VERIFY (L212) — is it really from the system?
  const signature = req.headers.get('x-webhook-signature');
  if (!verifySignature(signature, await req.text())) {   // HMAC (L212)
    return new Response('invalid signature', { status: 401 });
  }

  // 2 · VALIDATE (L163, L143) — the event contract.
  const event = EventSchema.parse(body);                 // the shape (L143)

  // 3 · DEDUPE (L255) — the at-least-once response.
  if (await alreadyProcessed(event.id)) {                // seen before?
    return new Response('duplicate', { status: 200 });   // 200, no work (L255)
  }

  // 4 · HAND OFF (L222) — the worker runs the workflow (L217).
  await queue.enqueue({ type: 'workflow.run', event });  // the in-tray (L222)
  await markProcessed(event.id);                         // the dedupe key (L255)

  return new Response('ok', { status: 200 });            // fast (L151)
}

// THE WORKER (L222) — off the event path.
async function worker() {
  for (const job of await queue.dequeue()) {
    await withRetry(() => runWorkflow(job.event));       // L169, L217
    await queue.ack(job);                                // or the dead letter (L232)
  }
}

What the reader must SEE — the guarded slot, end to end:

  verifySignature()    → the seal (L212)
  EventSchema.parse()  → the contract (L163, L143)
  alreadyProcessed()   → the dedupe (L255)
  queue.enqueue()      → the in-tray (L222) — 200, fast (L151)

  Events in, verified, deduplicated, queued — the path is designed.

• The endpoint is the fast path (L151). Verify, validate, dedupe, enqueue — microseconds (L220); the 200 returns before the work starts (L222).
• The queue is the throughput lever (L222). The in-tray (L222) absorbs the event bursts (L151) — the workers scale to the load (L222).
• The dedupe store is the idempotency cost (L255). A key-value lookup per event (L255) — cheap (L171), and the cache (L171) makes it faster (L220).
• The retries are the provider's clock (L232). The provider's retry schedule (L232) interacts with your idempotency (L255) — the design accounts for both (L220).

• Webhooks = the trigger side (L220): systems POST events to your endpoint.
• The guard: verify (L212), validate (L163), dedupe (L255).
• The handoff: enqueue (L222) + 200 fast (L151) — the worker runs the workflow (L217).
• The semantics: at-least-once (L255) — idempotency is the requirement (L220).
• The failure story: retries (L169), dead letters (L232).
• The path: the platform's front door (L230).

WEBHOOKS & EVENT-DRIVEN AUTOMATION = the trigger side of the workflow

THE PATH (L220)
  the system POSTs an event (L223-227)
  → VERIFY the signature (L212) — the seal
  → VALIDATE the contract (L163, L143) — the letter
  → DEDUPE by the event ID (L255) — the duplicates
  → HAND OFF to the queue (L222) — the in-tray
  → 200, fast (L151) — the worker runs the workflow (L217)

THE SEMANTICS (L255)
  delivery is at-least-once (L232) — providers retry
  the handler is idempotent by the event ID (L255)
  first arrival processes · duplicates 200 without work

THE SECURITY (L212)
  the signature (HMAC, L212) proves the sender
  the unsigned and the forged are rejected (L220)
  a forged event is an injection into the platform (L212)

THE FAILURES (L232)
  retries (L169) · dead letters (L222) · the replay story (L255)
  the event path's recovery is part of the design (L230)

INTERVIEW, 4 MOVES
  1 trigger "the systems POST events to my endpoint (L220)"
  2 guard   "verify (L212), validate (L163), dedupe (L255)"
  3 handoff "enqueue (L222) + 200 fast — the worker runs it (L217)"
  4 semantics "at-least-once (L255) — idempotency is the requirement"

You now hold the trigger side: the verified, validated, deduplicated mail slot that turns the business's events into workflow runs — fast, safe, and at-least-once. The automation now listens to the business (L230).

Next: the schedule that starts the work — scheduled jobs & cron for AI (L221), digests, reports, and syncs.