AWSAWS Certified Generative AI Developer - Professional2026-102.3 Design and implement enterprise integration architectures
Acknowledge webhooks after accepting durable work
Completed by the knowledge check
Learning objective
Integrate FM-enabled microservices through Amazon API Gateway and Lambda webhook handlers
Core idea
A webhook handler is an integration boundary, not the whole model workflow. It verifies the sender, validates the event, and decides whether it has accepted responsibility for processing. The response must describe that decision accurately. Returning success before durable acceptance can lose work; waiting for every model call can exceed the sender’s deadline and trigger duplicate deliveries.
Keep the microservice’s public contract independent of the foundation model (FM). A service can accept a document-classification request without exposing its prompt, model identifier, or internal tool chain. Model callers and their execution budgets are covered in 2.2.4. Here, the decision is where API acceptance ends and business processing begins.
How it works
Define the HTTP and identity contract
An API Gateway HTTP API can use a Lambda proxy integration. Set payloadFormatVersion explicitly to 1.0 or 2.0 when creating the integration through an SDK, the AWS CLI, or CloudFormation. The setting controls both the event delivered to Lambda and the interpretation of the function response.
For version 2.0, duplicate headers and query parameters are combined with commas rather than exposed through the version 1.0 multi-value fields. The event includes rawPath and rawQueryString, and the body can be base64 encoded. Make the handler parse the selected format deliberately. Do not assume a generic JSON parser also preserves the representation a webhook sender uses for signature verification.
If the sender supports JWT access tokens, configure an HTTP API JWT authorizer with the expected issuer, audience, and route scopes. The validated claims reach Lambda through requestContext.authorizer.jwt.claims. If the sender uses a provider-specific signature instead, validate that signature in the handler according to the sender’s documented signing contract. API Gateway’s JWT authorizer does not validate an arbitrary webhook signature.
Signature checking, payload parsing, and business validation are different steps. Authenticate the request representation before trusting its contents. Then validate the event type, schema version, source identifier, and resource access. The sender’s event identifier is useful for deduplication, but a payload field claiming another tenant does not grant that tenant’s access.
Return explicit acceptance outcomes
With payload format 2.0, API Gateway can infer an HTTP 200 response from valid JSON that lacks statusCode. That is convenient for uncomplicated responses but dangerous for acceptance logic. Return an explicit statusCode, headers, and body so that validation failures, dependency failures, and accepted work cannot accidentally look identical.
Use an application response contract such as:
| Response meaning | Handler responsibility |
|---|---|
| Rejected | Explain a permanent authentication or validation failure without accepting work |
| Accepted | Return the operation identifier after durable hand-off |
| Completed | Return the business result after all required processing succeeds |
| Temporarily unavailable | Signal that acceptance did not complete and a bounded retry may be appropriate |
An HTTP 202 is a useful application convention for accepted background work. It does not prove that the work finished. The caller needs a status resource, callback, or separate completion event if it must observe the eventual outcome. Choose one of these explicitly rather than making the caller infer completion from elapsed time.
Put long processing behind a durable hand-off
An HTTP API’s maximum integration timeout is 30 seconds and cannot be increased. Its payload-size quota is 10 MB. These are HTTP API limits, not universal limits for every API Gateway API type or downstream integration. The end-to-end path also has the sender’s timeout and each downstream component’s limits; use the tightest relevant constraint.
If inference or downstream processing does not fit that synchronous budget, the Lambda handler can hand a validated command to Amazon SQS before acknowledging it. Keep a stable event or operation identifier across retries. If the enqueue succeeds but the HTTP response is lost, a sender can redeliver the same event, so the worker must recognize repeated operations.
A Lambda SQS event source mapping polls the queue and invokes the function synchronously with batches. After a successful batch, Lambda deletes its messages. On a batch failure, messages become visible again after the visibility timeout. This asynchronous application architecture therefore still uses synchronous Lambda invocations internally; those two uses of “synchronous” describe different boundaries.
Configure FunctionResponseTypes with ReportBatchItemFailures when the worker can identify individual failed records. Return their identifiers in batchItemFailures using itemIdentifier. This prevents successful records from being needlessly retried with a failed neighbor. It does not eliminate duplicate processing or make a downstream model invocation transactional.
Configure an SQS redrive policy with maxReceiveCount to move repeatedly failing messages to a dead-letter queue. Monitor ApproximateAgeOfOldestMessage for backlog age, but remember that standard queues can exclude repeatedly received poison messages from that age signal.
Keep acceptance and processing failures separately observable in the service’s operation records. A webhook accepted into the queue but later rejected by business validation is a processing failure. A handler that cannot enqueue has not accepted responsibility. A duplicate that references an already completed operation should return the established result or status rather than run the workflow again.
Key distinctions and trade-offs
A synchronous handler offers a result in one exchange, but couples the sender to model latency and dependency health. A queue-backed handler responds after hand-off and absorbs processing delays, but adds an eventual outcome contract and backlog management. The choice follows the caller’s required result, not whether Lambda appears in the diagram.
Batch failure handling and operation idempotency solve different problems. ReportBatchItemFailures narrows retries to failed records; a stable operation identifier prevents repeated records from causing repeated business effects. Keep both when a worker performs consequential writes.
An authenticated webhook also differs from a public inference endpoint. The webhook’s job is to accept a known event contract. Giving it arbitrary model instructions or model-routing parameters expands its authority and makes its behavior harder to govern.
Architecture / decision scenario
A support platform sends ticket-created webhooks to a summarization microservice. Some tickets contain attachments that require processing before a model can summarize them. The sender expects a prompt HTTP acknowledgment and can retry when it receives no response.
The team fixes the proxy integration at payload format 2.0. The handler validates the sender’s documented signature before interpreting the ticket, checks the allowed event type, and enqueues a command with the original event identifier. It returns an explicit 202 and an operation identifier after the queue hand-off succeeds.
A Lambda worker processes SQS batches and reports individual failures through ReportBatchItemFailures. Repeated ticket events resolve to the same operation. The microservice records completion separately and exposes status to the support platform. A short interactive request that reliably fits the caller’s deadline can use a synchronous result route, but it does not share the webhook’s acceptance-only response meaning.
Common exam traps
- Returning inferred
200responses for every outcome. - Treating
202as proof of completed inference. - Assuming every sender supports JWT authentication.
- Waiting beyond the HTTP API’s 30-second integration limit.
- Confusing SQS-triggered Lambda calls with Lambda’s asynchronous invocation queue.
- Treating partial batch responses as end-to-end exactly-once processing.
What to remember
Fix the proxy payload format, authenticate the sender, and validate the event contract. Acknowledge only after the service has accepted responsibility for the work. Use a queue when processing exceeds the synchronous budget, and preserve operation identity across redelivery. Separate the initial HTTP outcome from eventual model and business outcomes.
Knowledge check
A support platform sends ticket webhooks to an HTTP API with a Lambda proxy integration and retries when it gets no response. Attachment processing and summarization often take several minutes. When should the handler return 202 with an operation identifier?
202 claims that the service has accepted responsibility, which is true only after authentication, validation and a durable hand-off such as an SQS enqueue. Waiting for summarization cannot work, because an HTTP API’s 30-second integration timeout cannot be raised. Acknowledging earlier can lose work or accept an event from an unverified sender.A webhook handler on payload format 2.0 catches a failed SQS enqueue and returns {"error": "queue unavailable"}. The sender treats the event as delivered and never retries, so the ticket is lost. Which change fixes the acknowledgment?
statusCode that signals temporary unavailability2.0 , valid JSON without a statusCode is inferred as 200 , so the failed hand-off looked like success. An explicit status keeps rejected, accepted and temporarily unavailable outcomes distinct, and lets the sender retry. A dead-letter queue only receives messages that reached the queue, and logging does not change what the sender sees.A webhook sender signs each request with its own documented signature over the raw body and cannot obtain JWT access tokens. Where should the signature be verified?
The SQS worker reports failed records through ReportBatchItemFailures. A ticket event was enqueued, but the HTTP response was lost and the sender delivered it again. What prevents a second summary from being written?
batchItemFailuresmaxReceiveCount