Webhook Architecture for Agent-Triggered Repository Events

Webhook architecture is the event layer that makes agent-triggered repository workflows possible. Its production reliability depends on more than receiving a request. The endpoint, routing layer, security checks, retry handling, and agent state must work as one system, with clear boundaries between accepting an event and acting on it.

Why repository events need a purpose-built event layer, not polling

Polling uses compute to ask whether something has changed, even when nothing has happened. It also leaves a gap between the event and the next request that discovers it. For an agent expected to react to a CI failure, a PR merge, or a merge queue entry, polling intervals measured in minutes are structurally inadequate. Even with a shorter interval, polling does the work again and finds out about changes late.

Webhooks reverse that arrangement by sending events when they happen and costing nothing when nothing happens. This makes them the right trigger primitive for repository workflows, with more to offer than the ease of replacing scheduled requests. The distinction matters because the event layer must support both the start of agent work and the return of its results. A trigger brings an event from outside into an AI workload, while a callback brings back a completion event from asynchronous AI work. Together, these two roles connect the application to the systems it acts on without requiring continuous polling.

That scope gives the event layer a precise responsibility. It sends notifications across system boundaries so that agents can act when something happens in a repository or when asynchronous work is complete. The agent’s reasoning belongs downstream of that boundary.

What the webhook endpoint itself must and must not do

The endpoint’s job is to accept the payload, verify its signature, hand it to a queue, and return a fast acknowledgment. Heavy processing must happen asynchronously. This separation is a correctness requirement because major webhook providers enforce delivery timeouts. Model inference regularly exceeds those limits, so calling an LLM inside the request handler can cause the provider to mark a delivery as failed and begin retrying.

Signature verification belongs before payload parsing. GitHub supplies the signature in the X-Hub-Signature-256 header, and the endpoint checks it using HMAC-SHA256 against the shared secret. Cloudflare Agents documentation illustrates this order by receiving the raw body as text and checking the signature against the digest. Its handler rejects failed verification with 401 before parsing the body. Only after verification does it parse the payload and hand off to processEvent.

The important feature of that example is the boundary it preserves. The edge receives and verifies the event, and later stages interpret it and do the work. A fast acknowledgment therefore means the event has been accepted for processing.

How to route, fan out, and isolate events across agent instances

After an event reaches the queue, routing determines which agent or child task should receive it. The router inspects the event type, but event type alone does not define the ownership of state. Each webhook source also needs an isolated agent instance rather than a shared handler that accumulates state from unrelated sources. For repository workflows, that means one agent per repository, with its own persistent storage.

Cloudflare Agents derives the agent name from payload.repository.full_name, lowercasing it and replacing slashes with hyphens. It then uses getAgentByName to send the event to the dedicated instance. This gives repository identity a concrete role in the architecture rather than leaving separation to application conditionals. Cloudflare Agents shows how to use the same isolation pattern for CI/CD pipeline agents, issue tracker agents, and per-customer payment agents. The shared principle is that an entity’s events reach the agent that owns its state.

Within that boundary, fan-out assigns different work to separate child tasks. Hookdeck and Trigger.dev demonstrate a router that sends pull_request events with opened or synchronize actions to PR review, issues events with an opened action to issue labeling, and push events to deployment summaries in Slack. Or Hookdeck connection routing can use header filters to send each event type straight to the right task. Moving those decisions upstream reduces branching inside the application.

The security requirements that cannot be deferred to later

Correct routing is useful only if the event is allowed to reach the agent in the first place. HMAC signature verification on every incoming request is the baseline, but it is not the complete security contract. A production endpoint also requires timestamp validation to resist replay attacks, HTTPS enforcement, rate limiting, and payload schema validation before data reaches agent logic. These checks address different properties of the request, so a valid signature does not make the others redundant. Deferring them until after the agent is connected leaves the acceptance boundary incomplete.

OpenAI, Google, and Anthropic use closely aligned designs built around HMAC or JWT signatures and a short freshness window of roughly five minutes. The relevant principle for GitHub webhook architecture is the combination of source authentication and replay resistance. A signature establishes where the payload came from, while freshness checks address whether an otherwise valid request is being presented again outside the accepted window. Schema validation then checks that the data that was accepted has the shape the agent expects.

Anthropic’s managed agent webhooks automatically disable an endpoint after a sustained period of continuous delivery failures. The endpoint is turned off based on how long delivery has been failing rather than how many deliveries have failed, and it stays off until someone manually turns it back on. Reward-path agents must account for this policy because endpoint failures can both delay a request and stop later notifications.

Why idempotency and dead letter queues are reliability, not edge cases

An agent that gets a duplicate event can take real action twice. This is not equivalent to writing a duplicate log entry, because the event is an instruction to begin work. Webhook providers guarantee at-least-once delivery rather than exactly-once delivery, so duplicates are an expected property of production pipelines. Security checks do not remove that property. A delivery can come from a trusted source and still be one that should not run again.

Idempotency handling must therefore detect duplicates before they reach agent logic. The system can use the event GUID from X-GitHub-Delivery or a hash of the event type and a stable identifier as its idempotency key. Keeping that key with a TTL lets the pipeline spot and skip deliveries it has seen before. OpenAI, Google, and Anthropic explicitly warn that duplicates occur and identify deduplication on a delivery ID as the expected handling pattern.

A dead letter queue captures events that exhaust their retry attempts so that they remain available for inspection or reprocessing. Without that destination, a dropped event can represent a missed merge, a skipped CI gate, or a workflow that never ran.

The merge_group event as the primary webhook surface for software factories

For software factories driven by agents that use merge queues, merge_group takes the place of pull_request as the main webhook surface. GitHub dispatches a checks_requested event under the merge_group event family when a PR enters the merge queue. The queue then awaits a response from the CI provider. A provider or agent orchestrator that is not explicitly subscribed to that event does not run for the queue flow. A pipeline can therefore handle ordinary PR activity correctly while remaining absent from the point where queue checks are requested.

This event-subscription problem persists through additional retries. Delivery infrastructure can reliably process only the events the pipeline is configured to receive. CI providers and agent orchestrators must explicitly subscribe to merge_group so that queue flows do not bypass their checks. The distinction changes the role of webhook configuration from a notification preference to part of the gate itself.

Build concurrency adds a separate control over how much queue work begins at once. It sets the maximum number of merge_group webhooks dispatched simultaneously, which throttles concurrent CI builds and affects how quickly the queue can complete merges.

State coherence: the failure mode that HMAC and retries cannot catch

Even with the correct subscriptions, authenticated delivery, and duplicate handling, an agent can proceed from an incorrect account of what happened. A state coherence failure occurs when an event is delivered, verified, processed, and acknowledged while the agent’s durable record remains incomplete or out of order. The transport has done its job, but the agent’s memory does not faithfully represent the sequence of actions. Successful delivery is therefore necessary evidence of reliability, but it is not sufficient evidence of correct behavior.

This failure is harder to recognize than a crash because a crash provides a clear boundary and a traceable error. A state coherence failure can leave a transcript that appears consistent even though actions were recorded incorrectly or not recorded at all. The agent then continues from a false premise. HMAC cannot expose that discrepancy because it authenticates only the incoming payload. Retries likewise deal with failures in delivery or processing, but they do not prove that the durable record is complete.

The thin-payload design used by major providers points toward a useful separation of responsibilities. An event can carry its type and a resource ID rather than the full result, allowing the endpoint to acknowledge quickly and hydrate the full object asynchronously. Reconciliation against the API then accounts for anything that may have been missed, making it the step where state coherence is maintained. Production readiness also requires trajectory-level evaluation of the agent’s behavior across a sequence of events. Tool-call accuracy and task completion checks test how the agent behaved across those events as well as whether each notification was processed.

How composable infrastructure applies this architecture without rebuilding it each time

Most teams should assemble this architecture from purpose-built components rather than build the entire webhook-to-agent pipeline from scratch. The boundaries established throughout the pipeline provide the contracts for that composition. A webhook edge handles delivery, verification, and retry, while a durable task runtime handles execution and fan-out. Agent-specific infrastructure handles the merge queue, transcript evaluation, and code storage layer. Each component has a distinct responsibility whose success can be assessed without confusing it with the success of the whole workflow.

Hookdeck owns signature verification, payload transformation, retry, and observability at the webhook edge. Trigger.dev takes care of durable execution, typed payloads, and fan-out to child tasks. Because those responsibilities are separated, either component can be replaced or upgraded without rebuilding the entire pipeline. Cloudflare Agents supplies another composable primitive through per-entity isolation and persistent state, making the state ownership layer replaceable as well.

A monolithic platform instead puts events, routing, agent execution, and the work of managing the merge queue together in one product. When faster CI, different routing logic, or a new event type requires a change, the platform as a whole must accommodate it. With composability, each change stays with the component that handles that part of the work. The production requirement is a set of clear contracts that carry an authentic event through reliable execution into a coherent record of what the agent actually did.