Webhooks

A webhook is an integration pattern in which an application sends an HTTP request to a configured callback URL when a selected event occurs. The request commonly uses HTTPS POST and contains a JSON payload describing the event, its identifier, and relevant resources. Unlike polling, where a consumer repeatedly asks whether anything changed, a webhook pushes a notification when the producer detects a change. This can reduce unnecessary requests and shorten the time between an event and its processing.

In CI/CD, a source repository can send webhook events when developers open or update pull requests or merge code. A build service can filter these events and run compilation, unit tests, security checks, or integration tests. For example, AWS CodeBuild supports webhook-triggered builds for supported repository providers. Configure filters for the intended event types and branches rather than building on every repository action. A merge may be represented by a pull-request-merged event or by a push to the destination branch, depending on the provider and integration. Selecting overlapping triggers can cause duplicate builds.

Starting a build is not the same as enforcing a merge gate. Publish test results through the repository integration and configure branch protection or repository rules to require the appropriate checks. Treat code from untrusted pull requests as potentially hostile: it can change build scripts and attempt to extract credentials. Use restricted build roles, isolate execution, and avoid exposing deployment secrets to untrusted contributions.

For enterprise integrations, an HTTPS endpoint can receive events from a ticketing system, customer relationship management application, or document platform. An API gateway routes requests to a webhook handler, which validates the sender, checks the payload, and accepts work for asynchronous processing. For example, Amazon API Gateway and AWS Lambda can receive a ticket-created event, then publish a normalized event to Amazon EventBridge or place work on Amazon SQS. A downstream worker can invoke a generative AI model to summarize the ticket or draft a response, then update the originating application through its API.

Webhook handlers should return a successful response promptly, but only after the event has been durably accepted for processing. Performing a long build or model invocation before responding risks exceeding the sender's timeout. A successful acknowledgment usually means the notification was accepted, not that the business workflow completed. Track completion separately and design status updates so they do not create notification loops.

Security depends on the producer's supported authentication mechanism. When signatures are available, verify them using the documented algorithm and the original request bytes; parsing and reserializing JSON can invalidate a signature. Use timestamps and delivery identifiers to help reject replays, rotate signing secrets, and enforce payload limits. HTTPS protects transport but does not, by itself, prove that the caller is the expected application. In AI workflows, treat event text as untrusted input and do not allow embedded instructions to grant tool access or bypass authorization.

Webhooks do not inherently guarantee delivery, ordering, or exactly-once processing. Retry policies vary by sender, and timeouts can cause redelivery even when processing succeeded. Make consumers idempotent using a stable event identifier, use bounded retries and dead-letter handling downstream, and monitor delivery failures and processing lag. For critical integrations, provide reconciliation against the source system because receiver-side queues cannot recover an event that never arrived. Webhooks provide lightweight connectivity, but they are not a substitute for a durable message broker or a complete workflow engine.