The Webhook Receiver

// Mount express.raw ONLY on the receiver path, before the global json() parser.
// This hands the handler a Buffer of the exact bytes Sent signed.
app.use("/webhooks", express.raw({ type: "application/json" }));

// In the handler:
const rawBody: Buffer = Buffer.isBuffer(req.body)
  ? req.body
  : Buffer.from(typeof req.body === "string" ? req.body : JSON.stringify(req.body ?? {}));

# FastAPI: read the body as bytes BEFORE any Pydantic model binding.
@router.post("/sent")
async def receive(request: Request):
    raw_body: bytes = await request.body()
    id_ = request.headers.get("x-webhook-id")
    timestamp = request.headers.get("x-webhook-timestamp")
    signature = request.headers.get("x-webhook-signature")
    # ... verify(raw_body, ...) then json.loads(raw_body) only after

// Echo: read the whole body into bytes; do not bind a struct first.
rawBody, err := io.ReadAll(c.Request().Body)
if err != nil {
    return c.JSON(http.StatusBadRequest, echo.Map{"error": "cannot read body"})
}
id := c.Request().Header.Get("X-Webhook-ID")
timestamp := c.Request().Header.Get("X-Webhook-Timestamp")
signature := c.Request().Header.Get("X-Webhook-Signature")
// verify(rawBody, ...) then json.Unmarshal(rawBody, &event) after

// Spring: bind the body as a raw String (or byte[]), NOT a parsed DTO.
@PostMapping("/webhooks/sent")
public ResponseEntity<?> receive(
    @RequestBody String rawBody,
    @RequestHeader("X-Webhook-ID") String id,
    @RequestHeader("X-Webhook-Timestamp") String timestamp,
    @RequestHeader("X-Webhook-Signature") String signature) {
  // verify(rawBody, ...) then objectMapper.readValue(rawBody, ...) after
}

// ASP.NET Core: read the request body stream yourself.
[HttpPost("/webhooks/sent")]
public async Task<IActionResult> Receive()
{
    using var reader = new StreamReader(Request.Body);
    var rawBody = await reader.ReadToEndAsync();
    var id = Request.Headers["X-Webhook-ID"].ToString();
    var timestamp = Request.Headers["X-Webhook-Timestamp"].ToString();
    var signature = Request.Headers["X-Webhook-Signature"].ToString();
    // Verify(rawBody, ...) then JsonSerializer.Deserialize(rawBody) after
}

// Laravel: getContent() returns the raw request body verbatim.
public function receive(Request $request)
{
    $rawBody   = $request->getContent();
    $id        = $request->header('X-Webhook-ID');
    $timestamp = $request->header('X-Webhook-Timestamp');
    $signature = $request->header('X-Webhook-Signature');
    // verify($rawBody, ...) then json_decode($rawBody) after
}

# Rails: request.raw_post is the unparsed body. Skip CSRF for this action.
def receive
  raw_body  = request.raw_post
  id        = request.headers["X-Webhook-ID"]
  timestamp = request.headers["X-Webhook-Timestamp"]
  signature = request.headers["X-Webhook-Signature"]
  # verify(raw_body, ...) then JSON.parse(raw_body) after
end

// Verified above. Parse the envelope, ack, THEN process.
let event: WebhookEvent;
try {
  event = WebhookEventSchema.parse(JSON.parse(rawBody.toString("utf8")));
} catch {
  return res.status(400).json({ error: "invalid payload" });
}

// Acknowledge immediately so Sent doesn't retry while we work.
res.status(200).json({ received: true });

// Dedupe on a per-event key (NOT X-Webhook-ID — that's the endpoint id).
const { message_id, message_status } = event.payload;
if (message_id && !idempotency.firstSeen(`${message_id}.${message_status}`)) return; // dup — no-op
void processEvent(eventType ?? event.event, event, logger);

# Verified above. Ack, then hand off (BackgroundTasks or a real queue).
try:
    event = json.loads(raw_body)
except ValueError:
    return JSONResponse({"error": "invalid payload"}, status_code=400)

# Dedupe on a per-event key (NOT X-Webhook-ID — that's the endpoint id).
payload = event.get("payload", {})
key = f"{payload.get('message_id')}.{payload.get('message_status')}"
if payload.get("message_id") and not idempotency.first_seen(key):
    return JSONResponse({"received": True})  # duplicate — no-op

background_tasks.add_task(process_event, event_type, event)
return JSONResponse({"received": True})

// Verified above. Parse, dedupe, ack; process in a goroutine.
var event WebhookEvent
if err := json.Unmarshal(rawBody, &event); err != nil {
    return c.JSON(http.StatusBadRequest, echo.Map{"error": "invalid payload"})
}

// Dedupe on a per-event key (NOT X-Webhook-ID — that's the endpoint id).
key := event.Payload.MessageID + "." + event.Payload.MessageStatus
if event.Payload.MessageID != "" && !idempotency.FirstSeen(key) {
    return c.JSON(http.StatusOK, echo.Map{"received": true}) // duplicate — no-op
}

go processEvent(eventType, event) // process off the response path
return c.JSON(http.StatusOK, echo.Map{"received": true})