StoryboardAI Engineering

Webhooks and queues

A webhook lets another system start your agent. A queue lets the agent take the work at its own pace.

What are webhooks and queues?

Many agents are never chatted with. They start because something happened somewhere else: a pull request was opened, an email arrived, a form was submitted. The usual way to hear about it is a webhook. You give the other system an address, and it sends a short message there each time the event occurs.

Anyone who learns the address could send a fake message, so each real one is signed with a secret that only the two systems know. The receiver checks the signature before doing anything.

The sender expects a quick acknowledgement, often within seconds, and an agent's work takes minutes. So the receiver does not do the work straight away. It writes a job into a queue, a waiting line, and acknowledges at once. Separate workers take jobs from the line a few at a time.

The queue also absorbs a rush. Thirty events in a minute become thirty waiting jobs, not thirty model calls fired together into a rate limit. And if a worker crashes half way, the job is still in the line to be tried again, which is why each job should be safe to run twice.

From an event to a job to a worker.Step 1: Something happens elsewhere. Step 2: A signed message arrives. Step 3: It becomes a job in a queue. Step 4: A worker takes it when free.1Something happenselsewhere2A signed messagearrives3It becomes a jobin a queue4A worker takes itwhen free
From an event to a job to a worker.

Why do webhooks and queues matter?

Many agents are never chatted with. They start because something happened elsewhere: a pull request opened, an email arrived, a file was uploaded. Webhooks are how an agent hears about it. Queues are how it copes when a great many things happen at once, and how it recovers when a worker fails half way.

How do webhooks and queues work?

  1. You give another system an address. It sends a short message there whenever a chosen event occurs.
  2. Your receiver checks the message's signature to be sure it is real.
  3. It writes a job into a queue and acknowledges at once.
  4. Workers take jobs from the queue a few at a time and do the real work.
  5. A job is removed only when its worker reports success. If the worker dies, the job reappears.

When should you use webhooks and queues?

Use it when

  • Work should start from an event, not from a person asking
  • Events arrive in bursts
  • Each piece of work takes longer than the sender will wait

Think twice when

  • A person is waiting for an answer in a conversation
  • There is only ever one thing to do at a time

Where do webhooks and queues sit in a real system?

The webhook receiver is a small public endpoint. The queue sits behind it. The workers that run the harness take from the queue. The three are separate so that a rush or a crash in one does not stop the others.

What goes wrong with webhooks and queues?

  • Doing the long work before acknowledging, so the sender gives up and sends again.
  • Skipping the signature check, so anyone can trigger your agent.
  • Assuming each event arrives once. Make every job safe to run twice.

What does webhooks and queues look like in practice?

Thirty pull requests open in a minute. Each event is acknowledged in 0.2 seconds and queued. Three workers review at a time. One dies after 70 seconds. Its job reappears five minutes later and another worker completes it.

Watch it happen

These stories show webhooks and queues at work, one step at a time.