Push vs Pull

<?php

declare(strict_types=1);

/**
 * Webhook receiver (push model).
 *
 * Trade-off notes:
 * - Caller (Stripe/GitHub) initiates delivery, we must be online.
 * - Idempotency is mandatory: providers retry on 5xx / timeout.
 * - Must verify signature to avoid spoofing.
 * - 200 OK must be sent fast; heavy work goes to a queue.
 */
final class StripeWebhookController
{
    public function __construct(
        private readonly SignatureVerifier $verifier,
        private readonly IdempotencyStore $idempotency,
        private readonly MessageQueue $queue,
    ) {}

    public function handle(Request $request): Response
    {
        $signature = $request->headers->get('Stripe-Signature') ?? '';
        $payload = $request->getContent();

        if (!$this->verifier->verify($payload, $signature)) {
            return new Response('invalid signature', 401);
        }

        $event = json_decode($payload, true, 512, JSON_THROW_ON_ERROR);
        $eventId = (string) $event['id'];

        // Idempotency: Stripe may retry, we process exactly once.
        if (!$this->idempotency->markProcessed($eventId)) {
            return new Response('duplicate', 200);
        }

        // Offload heavy work to worker, respond fast to avoid retry.
        $this->queue->publish('stripe.event', $event);

        return new Response('ok', 200);
    }
}

package poller

import (
	"context"
	"encoding/json"
	"net/http"
	"time"
)

// Poller fetches remote state periodically (pull model).
//
// Trade-off notes:
//   - Latency >= poll interval; bursts invisible between polls.
//   - Uses cursor (If-Modified-Since / since_id) to avoid refetching.
//   - Backoff on errors, no retries needed on remote side.
type Poller struct {
	client   *http.Client
	url      string
	interval time.Duration
	cursor   string
	handler  func(Event) error
}

func (p *Poller) Run(ctx context.Context) error {
	ticker := time.NewTicker(p.interval)
	defer ticker.Stop()

	for {
		select {
		case <-ctx.Done():
			return ctx.Err()
		case <-ticker.C:
			if err := p.tick(ctx); err != nil {
				// Log and continue; next tick will retry.
				continue
			}
		}
	}
}

func (p *Poller) tick(ctx context.Context) error {
	req, _ := http.NewRequestWithContext(ctx, http.MethodGet, p.url+"?since="+p.cursor, nil)
	resp, err := p.client.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()

	var page struct {
		Events []Event `json:"events"`
		Next   string  `json:"next_cursor"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&page); err != nil {
		return err
	}
	for _, e := range page.Events {
		if err := p.handler(e); err != nil {
			return err // Stop: will resume from same cursor.
		}
	}
	p.cursor = page.Next
	return nil
}

type Event struct {
	ID   string          `json:"id"`
	Type string          `json:"type"`
	Data json.RawMessage `json:"data"`
}

using System;
using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

// ---- Push: webhook receiver ----
//
// Trade-off notes:
//   - The caller (Stripe/GitHub) initiates delivery, so we must be online.
//   - Idempotency is mandatory: providers retry on 5xx / timeout.
//   - The signature must be verified to avoid spoofing.
//   - 200 OK must be returned fast; heavy work goes to a queue.
[ApiController]
[Route("webhooks/stripe")]
public sealed class StripeWebhookController(
    ISignatureVerifier verifier,
    IIdempotencyStore idempotency,
    IMessageQueue queue) : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> Handle(CancellationToken ct)
    {
        using var reader = new StreamReader(Request.Body);
        var payload = await reader.ReadToEndAsync(ct);
        var signature = Request.Headers["Stripe-Signature"].ToString();

        if (!verifier.Verify(payload, signature))
        {
            return Unauthorized("invalid signature");
        }

        var evt = JsonSerializer.Deserialize<StripeEvent>(payload)
                  ?? throw new JsonException("empty payload");

        // Idempotency: Stripe may retry, we process exactly once.
        if (!await idempotency.MarkProcessedAsync(evt.Id, ct))
        {
            return Ok("duplicate");
        }

        // Offload heavy work to a worker, respond fast to avoid a retry.
        await queue.PublishAsync("stripe.event", evt, ct);

        return Ok("ok");
    }
}

public readonly record struct StripeEvent(string Id, string Type, JsonElement Data);

// ---- Pull: poller as a hosted background service ----
//
// Trade-off notes:
//   - Latency >= poll interval; bursts are invisible between polls.
//   - A cursor (since_id) avoids refetching the same page.
//   - On error we simply wait for the next tick; no remote retry needed.
public sealed class EventPoller(
    HttpClient client,
    ILogger<EventPoller> logger,
    Func<StripeEvent, CancellationToken, Task> handler) : BackgroundService
{
    private static readonly TimeSpan Interval = TimeSpan.FromSeconds(30);
    private string _cursor = string.Empty;

    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        using var timer = new PeriodicTimer(Interval);

        while (await timer.WaitForNextTickAsync(ct))
        {
            try
            {
                await TickAsync(ct);
            }
            catch (HttpRequestException ex)
            {
                // Log and continue; the next tick resumes from the same cursor.
                logger.LogWarning(ex, "poll failed, will retry at next tick");
            }
        }
    }

    private async Task TickAsync(CancellationToken ct)
    {
        var page = await client.GetFromJsonAsync<EventPage>($"?since={_cursor}", ct);
        if (page is null)
        {
            return;
        }

        foreach (var evt in page.Events)
        {
            await handler(evt, ct);
        }

        _cursor = page.NextCursor;
    }

    private sealed record EventPage(StripeEvent[] Events, string NextCursor);
}

from __future__ import annotations

import asyncio
import logging
from typing import Any, Awaitable, Callable

import httpx
from fastapi import APIRouter, Request, Response, status

logger = logging.getLogger(__name__)
router = APIRouter()

# ---- Push: webhook receiver ----
#
# Trade-off notes:
#   - The caller (Stripe/GitHub) initiates delivery, so we must be online.
#   - Idempotency is mandatory: providers retry on 5xx / timeout.
#   - The signature must be verified to avoid spoofing.
#   - 200 OK must be returned fast; heavy work goes to a queue.

@router.post("/webhooks/stripe")
async def handle_stripe_webhook(
    request: Request,
    verifier: SignatureVerifier,
    idempotency: IdempotencyStore,
    queue: MessageQueue,
) -> Response:
    payload = await request.body()
    signature = request.headers.get("stripe-signature", "")

    if not verifier.verify(payload, signature):
        return Response("invalid signature", status_code=status.HTTP_401_UNAUTHORIZED)

    event: dict[str, Any] = await request.json()

    # Idempotency: Stripe may retry, we process exactly once
    if not await idempotency.mark_processed(event["id"]):
        return Response("duplicate", status_code=status.HTTP_200_OK)

    # Offload heavy work to a worker, respond fast to avoid a retry
    await queue.publish("stripe.event", event)

    return Response("ok", status_code=status.HTTP_200_OK)

# ---- Pull: poller ----
#
# Trade-off notes:
#   - Latency >= poll interval; bursts are invisible between polls.
#   - A cursor (since_id) avoids refetching the same page.
#   - On error we simply wait for the next tick; no remote retry needed.
class Poller:
    def __init__(
        self,
        client: httpx.AsyncClient,
        url: str,
        handler: Callable[[dict[str, Any]], Awaitable[None]],
        interval: float = 30.0,
    ) -> None:
        self._client = client
        self._url = url
        self._handler = handler
        self._interval = interval
        self._cursor = ""

    async def run(self) -> None:
        while True:
            try:
                await self._tick()
            except httpx.HTTPError:
                # Log and continue; the next tick resumes from the same cursor
                logger.warning("poll failed, will retry at next tick", exc_info=True)

            await asyncio.sleep(self._interval)

    async def _tick(self) -> None:
        response = await self._client.get(self._url, params={"since": self._cursor})
        response.raise_for_status()
        page = response.json()

        for event in page["events"]:
            await self._handler(event)

        self._cursor = page["next_cursor"]