Handle webhooks idempotently

app.post(
  "/webhooks/salaf",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    // 1. Verify BEFORE parsing or trusting anything.
    const ok = verifySalafSignature(
      req.body,
      req.get("X-Salaf-Signature"),
      process.env.SALAF_WEBHOOK_SECRET,
    );
    if (!ok) {
      return res.sendStatus(400); // we will not retry a 4xx into working
    }

    const event = JSON.parse(req.body.toString("utf8"));
    const eventId = req.get("X-Salaf-Event-Id"); // === event.id

    // 2. Dedupe. Delivery is at-least-once: the same event WILL arrive
    // twice eventually. A unique index on the event id is the whole trick.
    const inserted = await db.query(
      `INSERT INTO salaf_events (id, type, payload)
       VALUES ($1, $2, $3) ON CONFLICT (id) DO NOTHING`,
      [eventId, event.type, event],
    );

    // 3. Answer FAST. Anything slower than a few hundred ms risks our 10s
    // timeout, and a timeout means a retry you did not need.
    res.sendStatus(200);

    if (inserted.rowCount === 0) {
      return; // already handled — nothing more to do
    }

    // 4. Do the work off the request. Order is NOT guaranteed, so write
    // upserts: order.updated may land before order.created.
    void queue.add("salaf-event", { eventId });
  },
);

async function handleEvent(event) {
  switch (event.type) {
    case "order.created":
    case "order.updated":
    case "order.paid":
      // data.object is the full snapshot as it was inside the transaction
      // that produced it — upsert it, do not patch field by field.
      return upsertOrder(event.data.object);
    case "inventory.updated":
      return setLevels(event.data.object.variant_id, event.data.object.levels);
    default:
      return; // unknown types are normal: the catalog only ever grows
  }
}

import json

from django.db import IntegrityError
from django.http import HttpResponse


@csrf_exempt
@require_POST
def salaf_webhook(request):
    # 1. Verify before trusting the body.
    if not verify_salaf_signature(
        request.body,
        request.headers.get("X-Salaf-Signature"),
        settings.SALAF_WEBHOOK_SECRET,
    ):
        return HttpResponse(status=400)

    event = json.loads(request.body)
    event_id = request.headers["X-Salaf-Event-Id"]  # same as event["id"]

    # 2. Dedupe on the event id — delivery is at-least-once.
    try:
        SalafEvent.objects.create(
            id=event_id, type=event["type"], payload=event
        )
    except IntegrityError:
        return HttpResponse(status=200)  # already seen; still a success

    # 3. Queue the work and answer immediately: our timeout is 10 seconds,
    # and a slow 200 costs you a duplicate you did not need.
    process_salaf_event.delay(event_id)
    return HttpResponse(status=200)


def handle_event(event):
    kind = event["type"]
    obj = event["data"]["object"]

    # 4. Upsert, never patch: events can arrive out of order, and every
    # payload carries the complete object as of its own transaction.
    if kind in ("order.created", "order.updated", "order.paid"):
        upsert_order(obj)
    elif kind == "inventory.updated":
        set_levels(obj["variant_id"], obj["levels"])
    # Unknown types are expected — the catalog only ever grows.

<?php

public function handle(Request $request)
{
    // 1. Verify first.
    if (! verify_salaf_signature(
        $request->getContent(),
        $request->header('X-Salaf-Signature'),
        config('services.salaf.webhook_secret'),
    )) {
        return response()->noContent(400);
    }

    $event = json_decode($request->getContent(), true);
    $eventId = $request->header('X-Salaf-Event-Id'); // same as $event['id']

    // 2. Dedupe on the event id (unique column). At-least-once delivery
    // means duplicates are routine, not exceptional.
    $isNew = SalafEvent::query()->insertOrIgnore([
        'id' => $eventId,
        'type' => $event['type'],
        'payload' => json_encode($event),
    ]) === 1;

    // 3. Queue and answer — the timeout is 10 seconds.
    if ($isNew) {
        SalafEventJob::dispatch($eventId);
    }

    return response()->noContent(200);
}

public function process(array $event): void
{
    $object = $event['data']['object'];

    // 4. Upsert: order.updated can arrive before order.created.
    match ($event['type']) {
        'order.created', 'order.updated', 'order.paid' => $this->upsertOrder($object),
        'inventory.updated' => $this->setLevels($object['variant_id'], $object['levels']),
        default => null, // unknown types are normal
    };
}