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.
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?
- You give another system an address. It sends a short message there whenever a chosen event occurs.
- Your receiver checks the message's signature to be sure it is real.
- It writes a job into a queue and acknowledges at once.
- Workers take jobs from the queue a few at a time and do the real work.
- 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.