Verifica prima. Elimina i duplicati prima degli effetti.

Contratto di consegna

Parte	Contratto
Eventi	booking.confirmed, booking.cancelled, booking.reschedule_requested, booking.rescheduled, booking.updated
Header	X-Fenix-Event-Id, X-Fenix-Delivery-Id, X-Fenix-Timestamp, X-Fenix-Signature e Idempotency-Key
Nomi di compatibilità	X-Fenix-, data-fenix- e FENIX_* sono nomi di protocollo legacy stabili. Mantienili invariati nelle integrazioni esistenti.
Firma	v1=<HMAC-SHA256(timestamp + "." + raw_body)> usando il segreto whsec_ monouso
Validità temporale	Accetta solo una finestra timestamp di cinque minuti e rifiuta version/type/reference non validi.
Tentativi	Cinque tentativi limitati con attese di 1m, 5m, 30m e 2h. 2xx completa; 3xx viene rifiutato e non seguito.

Flusso minimo di verifica

import { createHmac, timingSafeEqual } from 'node:crypto';

const rawBody = await request.text();
const timestamp = request.headers.get('x-fenix-timestamp') || '';
const signature = request.headers.get('x-fenix-signature') || '';
const ageSeconds = Math.abs(Date.now() - Number(timestamp) * 1000) / 1000;
const expected = 'v1=' + createHmac('sha256', process.env.FENIX_WEBHOOK_SECRET)
  .update(timestamp + '.' + rawBody)
  .digest('hex');
const received = Buffer.from(signature);
const candidate = Buffer.from(expected);

if (!Number.isInteger(Number(timestamp)) || ageSeconds > 300 ||
  received.length !== candidate.length || !timingSafeEqual(received, candidate)) {
  return new Response(null, { status: 400 });
}

const event = JSON.parse(rawBody);
if (await events.has(event.id)) return new Response(null, { status: 204 });

await database.transaction(async () => {
  await events.insert({ id: event.id });
  await applyBookingEvent(event);
});

return new Response(null, { status: 204 });

Politica di elaborazione del destinatario

Verifica la firma sul corpo grezzo non modificato prima di elaborare JSON. Convalida formato v1, finestra timestamp e schema evento atteso.
Salva atomicamente X-Fenix-Event-Id prima degli effetti. X-Fenix-Delivery-Id identifica un tentativo; Idempotency-Key ripete l’id evento per la deduplicazione.
Restituisci 2xx solo quando l’evento è gestito in sicurezza. I redirect sono rifiutati; gli errori ricevono al massimo cinque tentativi con attese di 1m, 5m, 30m e 2h.
Tratta i payload webhook come dati operativi. Escludili dalla telemetria browser e oscurali in log, ticket e rapporti.

Sicurezza dell’endpoint

Registra solo un hostname HTTPS pubblico. URL con credenziali, frammenti, query string o porte personalizzate vengono rifiutati.
La piattaforma risolve e convalida il DNS prima della configurazione e a ogni consegna; blocca destinazioni loopback, private, link-local, riservate e miste.
Il segreto di firma whsec_ monouso è mostrato al titolare solo alla creazione o rotazione. Conservalo in un secret manager server, ruotalo dopo un’esposizione e non inviarlo al supporto.
Sospendi l’endpoint durante un incidente. Ripeti solo consegne fallite o saltate quando il destinatario può deduplicare l’id evento originale.

Contratto di consegna

Parte	Contratto
Eventi	booking.confirmed, booking.cancelled, booking.reschedule_requested, booking.rescheduled, booking.updated
Header	X-Fenix-Event-Id, X-Fenix-Delivery-Id, X-Fenix-Timestamp, X-Fenix-Signature e Idempotency-Key
Nomi di compatibilità	X-Fenix-, data-fenix- e FENIX_* sono nomi di protocollo legacy stabili. Mantienili invariati nelle integrazioni esistenti.
Firma	v1=<HMAC-SHA256(timestamp + "." + raw_body)> usando il segreto whsec_ monouso
Validità temporale	Accetta solo una finestra timestamp di cinque minuti e rifiuta version/type/reference non validi.
Tentativi	Cinque tentativi limitati con attese di 1m, 5m, 30m e 2h. 2xx completa; 3xx viene rifiutato e non seguito.

Flusso minimo di verifica

import { createHmac, timingSafeEqual } from 'node:crypto';

const rawBody = await request.text();
const timestamp = request.headers.get('x-fenix-timestamp') || '';
const signature = request.headers.get('x-fenix-signature') || '';
const ageSeconds = Math.abs(Date.now() - Number(timestamp) * 1000) / 1000;
const expected = 'v1=' + createHmac('sha256', process.env.FENIX_WEBHOOK_SECRET)
  .update(timestamp + '.' + rawBody)
  .digest('hex');
const received = Buffer.from(signature);
const candidate = Buffer.from(expected);

if (!Number.isInteger(Number(timestamp)) || ageSeconds > 300 ||
  received.length !== candidate.length || !timingSafeEqual(received, candidate)) {
  return new Response(null, { status: 400 });
}

const event = JSON.parse(rawBody);
if (await events.has(event.id)) return new Response(null, { status: 204 });

await database.transaction(async () => {
  await events.insert({ id: event.id });
  await applyBookingEvent(event);
});

return new Response(null, { status: 204 });

Politica di elaborazione del destinatario

Verifica la firma sul corpo grezzo non modificato prima di elaborare JSON. Convalida formato v1, finestra timestamp e schema evento atteso.

Salva atomicamente X-Fenix-Event-Id prima degli effetti. X-Fenix-Delivery-Id identifica un tentativo; Idempotency-Key ripete l’id evento per la deduplicazione.

Restituisci 2xx solo quando l’evento è gestito in sicurezza. I redirect sono rifiutati; gli errori ricevono al massimo cinque tentativi con attese di 1m, 5m, 30m e 2h.

Tratta i payload webhook come dati operativi. Escludili dalla telemetria browser e oscurali in log, ticket e rapporti.

Sicurezza dell’endpoint

Registra solo un hostname HTTPS pubblico. URL con credenziali, frammenti, query string o porte personalizzate vengono rifiutati.

La piattaforma risolve e convalida il DNS prima della configurazione e a ogni consegna; blocca destinazioni loopback, private, link-local, riservate e miste.

Il segreto di firma whsec_ monouso è mostrato al titolare solo alla creazione o rotazione. Conservalo in un secret manager server, ruotalo dopo un’esposizione e non inviarlo al supporto.

Sospendi l’endpoint durante un incidente. Ripeti solo consegne fallite o saltate quando il destinatario può deduplicare l’id evento originale.