Un webhook de pagos que se procesa dos veces significa un cobro duplicado, un fulfillment doble o un inventario roto. Culqi —como casi todas las pasarelas— reintenta la entrega cuando no recibe un 200 a tiempo, así que la idempotencia no es opcional: es parte del contrato.
El primer paso es validar la firma HMAC de cada evento antes de hacer cualquier otra cosa. Si la firma no coincide con el secreto compartido, el evento se descarta con un 401 y se registra el intento. Esto elimina de raíz los eventos falsificados.
El segundo paso es deduplicar: cada evento trae un identificador único que guardo en una tabla de eventos procesados con un índice único. Si el insert falla por conflicto, el evento ya fue procesado y respondo 200 sin tocar nada más. Solo después de pasar ambos filtros el evento llega a la lógica de negocio.
Con este patrón, los reintentos de Culqi se vuelven inofensivos y el sistema puede procesar el mismo evento N veces con exactamente un efecto.