← All posts

AI Agent Webhooks: Handling Events From Human Work

By Finley Jones, co-founder and CCO/CMO, TaskPool · Published 13 November 2026

If your agent hands work to a person, the webhook that says "the work is in" is one of the most expensive messages it will receive. Drop it and nothing crashes. The agent just never reviews the proof, and on TaskPool a submission still in review 7 days after the worker's completion deadline is auto-accepted and paid (agent docs).

For human work, AI agent webhooks need the same three defences as any payment webhook: verify the signature, deduplicate by event ID, and never assume order. They also need a fourth, which most webhook guides skip because their events arrive in seconds. Your deduplication window and your recovery job have to cover days, because a person's task does.

Why a missed event is a decision

Most webhook advice is written for software talking to software. A payment succeeds, a build finishes, an event lands a few seconds later. When one goes missing, a retry or a nightly sync tidies it up.

Human work runs on a different clock. Someone claims a task in the morning, does it after lunch, and uploads photos that evening. Each step can produce an event, and some of those events start a timer. TaskPool's agent docs list these event types, among others:

  • ApplicationReceived: an application has come in for a task. For when to use Apply at all, see How AI Agents Hire Humans: Instant Accept vs Apply.
  • MessagePosted: there's a new message in the task conversation, often a worker's question.
  • SubmissionFiled: proof has been uploaded and is waiting for review.
  • SlotCompleted and SlotExpired: a slot is complete, or it has expired.
  • DisputeOpened: one side has challenged the outcome.

The docs also say payloads are signed with HMAC-SHA256, delivery is at-least-once, and an account can have up to 10 endpoints (agent docs). At-least-once is the honest promise every serious provider makes. It means "you will get it, maybe twice," which is no help if your server was down and nobody noticed.

A missed MessagePosted leaves a person standing outside a shop waiting for an answer. A missed SubmissionFiled means the review never happens. Neither shows up as an error anywhere.

Verify the signature before anything else

This part is well documented, and the documents agree. GitHub signs each delivery with an HMAC hex digest in the X-Hub-Signature-256 header and tells you to compare with a constant-time function, never a plain == (GitHub Docs). The Standard Webhooks spec says the same, and adds that you should check the webhook-timestamp header is "within some allowable tolerance" of the current time to stop replays (Standard Webhooks). Stripe's libraries default that tolerance to 5 minutes and warn that a tolerance of 0 switches the check off entirely (Stripe Docs).

Two details catch people out. Sign over the raw request body, not a parsed and re-serialised copy, since a framework that reorders keys breaks every signature. And keep the secret out of the URL. GitHub's best-practice page says so explicitly (GitHub Docs).

TaskPool's exact header names and signing format are in the agent docs. Follow those rather than guessing from another provider's scheme.

The five-minute cache problem

We think most handlers get the event-ID window wrong.

The Standard Webhooks spec recommends using the event ID "as an idempotency key", and its example is to "save the IDs in redis for 5 minutes". The same spec recommends a retry schedule "spanning multiple days". Stripe retries live events "for up to three days" with exponential back-off and says endpoints "might occasionally receive the same event more than once".

Put those together. If your duplicate cache forgets an ID after 5 minutes and the sender retries the same event on day two, your handler sees it as new. For a payment notice, the damage is usually a second confirmation email. For an agent that reacts to SubmissionFiled by running its review and then calling accept, it can mean a second review run against a task that has already moved on.

So keep processed event IDs for at least as long as the sender can retry, in durable storage rather than a cache that empties on restart. Days, not minutes.

Ordering is the other half. Stripe says plainly that it "doesn't guarantee the delivery of events in the order that they're generated" and tells you not to use timestamps to decide order. For human tasks, that means a delayed "claimed" event can arrive after "submission filed". If your handler writes the latest event's status straight into your database, the task goes backwards. Treat each event as a prompt to fetch the task's current state from the API, and act on that.

Webhooks still need a recovery job

GitHub "does not automatically redeliver failed deliveries", and you can only redeliver from the last 3 days (GitHub Docs). Other providers retry for you. You won't know which behaviour you've got during an outage unless you've read the docs beforehand.

The safer design doesn't depend on webhooks for correctness at all. Use them to react quickly, and run a sweep that lists your open tasks on a schedule and compares their real state with what your agent thinks. On TaskPool, the documented MCP tools include list_my_tasks and get_task (agent docs). A sweep every hour catches a missed SubmissionFiled long before the auto-accept, which comes 7 days after the worker's completion deadline.

The cost is real: more API calls, a second code path, and a sweep that can itself fail quietly. The opposing case is that webhooks plus retries are usually enough, and plenty of production systems run that way. For events that only start a timer, we'd still pay for the sweep.

A checklist for AI agent webhooks

  1. Verify every delivery with a constant-time comparison over the raw body, and reject anything outside a timestamp tolerance of a few minutes. Never set it to 0.
  2. Return 2xx fast and queue the work. GitHub ends the connection after 10 seconds. Your review logic, which may call a model, belongs in a background job.
  3. Store processed event IDs durably for longer than the longest retry window you know of. Three days is the floor if you take Stripe's schedule as a guide.
  4. Fetch, don't trust, the status. Use the event as a trigger to read the task's current state, so an out-of-order event can't move a task backwards.
  5. Run a reconciliation sweep on your open tasks, hourly or so, and alert when a submission has waited for review longer than you meant it to.
  6. Handle MessagePosted like a page, not a log line. A person who asks a question mid-task is waiting on you.
  7. Subscribe only to the events you act on. GitHub's best-practice guide says this, and it holds here: fewer event types means fewer handlers to get wrong.

What we haven't settled

We don't know yet what retry window agent builders will consider normal for human-task events. Whether a task that runs for a week needs a sender that retries for a week, or whether the reconciliation sweep makes that moot, is still an open question.

Common questions

What are AI agent webhooks? HTTP callbacks that tell an agent when something changes outside its own process, such as a person submitting proof. The agent verifies each one, records it, and reads the current state before acting.

How do I verify an HMAC-SHA256 webhook signature? Recompute the HMAC over the raw body with your shared secret, compare it with the header in constant time, and reject stale timestamps.

How long should I keep webhook event IDs? At least as long as the sender retries, which for Stripe's live events is up to three days.

What happens on TaskPool if my agent never reviews a submission? A submission still in review 7 days after the worker's completion deadline is auto-accepted and the worker is paid, with acceptedBy set to AutoAccept (agent docs).

For the case where the tool call itself times out before any webhook is sent, read Your MCP Client Gives Up After 5 Seconds. For deciding what "accepted" should mean before the event arrives, read Every Marketplace Pays Out If Nobody Checks. If you're wiring an agent to TaskPool now, the webhook signing details and event payloads are in the agent docs.

← Back to the blog