Event Triggers

## What an event source mapping is An **event source mapping** is the configuration that connects an event-producing service to a serverless function so that an event automatically triggers an invocation, without the developer writing any polling or subscription code themselves. Under the hood, every such mapping falls into one of two invocation mechanics: **push** or **poll**, and the mechanic is chosen by the source type, not by the developer. | Mechanic | Who calls whom | Named sources | |---|---|---| | Push | the event source calls the function | `API Gateway`, `S3`, `SNS` | | Poll | the platform reads the source | `SQS`, `Kinesis`, `Kafka`, `DynamoDB Streams` | ## The push model In the push model, the event source calls the function's invoke API directly the instant something happens. - **API Gateway** is the canonical example: when a client sends an HTTP request, API Gateway synchronously invokes the backing function, waits for the response, and streams it back to the client. - **S3 object-created notifications and SNS topic deliveries** work similarly but asynchronously — the source fires the event at the function and moves on without waiting for a reply, relying on the platform's internal retry queue if the invocation fails. In every push case, the source itself decides exactly when and how often the function is called; the serverless platform has no say in pacing beyond enforcing concurrency limits and throttling at the door. ## The poll model In the poll model, the source is a store the function cannot call out of — a queue like SQS, a log like Kinesis or Kafka, or a change stream like DynamoDB Streams. These sources are passive: they hold records until something reads them. So the serverless platform runs its own long-lived poller process (invisible to the developer) that: 1. continuously calls Receive/GetRecords-style APIs against the source, 2. accumulates records into a batch up to a configured size or time window, 3. and only then synchronously invokes the function with that batch as the payload. The poller is also responsible for checkpointing progress (deleting consumed SQS messages, advancing a Kinesis shard iterator) once the function returns successfully. ## Why the split exists This split exists because event sources have fundamentally different delivery semantics, and the platform has to bridge each one to a uniform 'invoke a function with a payload' contract. A queue or stream is designed to buffer and be read at the consumer's pace — there's no mechanism for it to reach out and call code. An API Gateway request, by contrast, has a live client on the other end waiting synchronously; buffering it centrally would defeat the purpose. Rather than force every function author to write bespoke polling loops for queue-based work, the platform absorbs that complexity into the poller component and exposes the same function-invocation interface everywhere. ## The trade-off The trade-off is between control and simplicity. - **Push** gives the lowest possible latency — no polling interval to wait out — and a simple mental model of 'one event in, one invocation out,' but it hands invocation-rate control to something outside the platform's process boundary. If ten thousand requests land in a second, the platform must throttle concurrently-running invocations and either queue or reject the excess; a burst that outruns configured concurrency shows up to the caller as 429s or 5xxs. - **Poll**, conversely, gives the platform itself the throttle: it will never pull records faster than the function can be invoked, so there's natural backpressure and the batch size can be tuned to trade latency for throughput. The cost is added latency (records sit until a batch fills or a timeout elapses) and a layer of polling infrastructure whose own health — poller concurrency, iterator age, empty-receive backoff — becomes something to monitor. ## Failure modes Failure modes differ correspondingly. - **On the push side**, an unconfigured or undersized concurrency limit causes silent event loss for asynchronous push sources unless a dead-letter queue is attached, because the source only retries a bounded number of times before giving up. - **On the poll side**, a single malformed or perpetually-failing record can stall an entire batch — and, for ordered sources like Kinesis, an entire shard — because the poller keeps re-delivering the same unconsumed batch instead of advancing past it (the so-called poison-pill problem). Iterator age or approximate-number-of-messages-visible metrics climbing steadily is the classic sign that a poller is falling behind or stuck. ## A concrete illustration A concrete illustration: a typical AWS Lambda-based order-processing pipeline uses API Gateway (push) to accept the initial 'place order' HTTP call synchronously, then drops a message onto SQS for asynchronous fulfillment work picked up by a second function via poll. The first hop needs sub-second, synchronous, per-request latency, so push is correct; the second hop benefits from batching, buffering against downstream slowness, and backpressure, so poll is correct. Choosing the wrong model — say, trying to synchronously push high-volume fulfillment events — would either overwhelm concurrency limits or lose events with no buffer to absorb bursts.