Quali piani supportano i webhook?

I webhook sono disponibili sui piani Pro, Business ed Enterprise. Sul piano gratuito i webhook non sono disponibili -- utilizzate l'esportazione manuale o l'API pubblica.

Quante volte tikento riprova l'invio in caso di errore?

Tre tentativi con ritardo esponenziale: dopo 1 minuto, dopo 5 minuti, dopo 30 minuti. Se tutti e tre i tentativi falliscono, l'evento viene contrassegnato come failed.

Come verificare la firma del webhook?

Calcolate l'HMAC-SHA256 del corpo della richiesta con il vostro webhook secret e confrontatelo con l'header X-Tikento-Signature. Utilizzate il confronto constant-time per la protezione dagli attacchi timing.

E possibile configurare piu URL per i webhook?

Si. Nella sezione Impostazioni - Integrazioni potete aggiungere piu URL e scegliere quali tipi di eventi inviare a ciascuno di essi.

Webhook: eventi e verifica della firma

Panoramica

I webhook permettono di ricevere notifiche sugli eventi della piattaforma tikento in tempo reale. Quando si verifica un evento (nuova registrazione, pagamento riuscito, annullamento dell'evento) tikento invia una richiesta HTTP POST al vostro URL con i dati dell'evento.

I webhook sono disponibili sui piani Pro, Business ed Enterprise.

Configurazione

Aggiunta dell'URL webhook

Aprite Impostazioni nel menu laterale.
Andate nella sezione "Integrazioni".
Cliccate "Aggiungi webhook".
Indicate l'URL dell'endpoint (HTTPS obbligatorio).
Selezionate i tipi di eventi che volete ricevere.
Cliccate "Salva".

Dopo il salvataggio tikento inviera una richiesta di test all'URL indicato per verificarne la raggiungibilita.

Webhook secret

Alla creazione del webhook il sistema generera un webhook secret -- una stringa per la verifica della firma. Salvatelo in un luogo sicuro. Il secret viene mostrato una sola volta.

Tipi di eventi

Evento	Descrizione
`registration.created`	Creata nuova registrazione
`registration.updated`	Aggiornati i dati della registrazione (stato, campi)
`payment.completed`	Pagamento completato con successo
`payment.refunded`	Effettuato rimborso del pagamento
`event.published`	Evento pubblicato
`event.cancelled`	Evento annullato

Potete iscrivervi a tutti i tipi o selezionare solo quelli necessari nelle impostazioni dell'integrazione.

Formato del payload

Ogni webhook viene inviato come HTTP POST con corpo in formato JSON.

Header della richiesta

Header	Descrizione
`Content-Type`	`application/json`
`X-Tikento-Event`	Tipo di evento (ad esempio, `registration.created`)
`X-Tikento-Signature`	Firma HMAC-SHA256 del corpo della richiesta
`X-Tikento-Timestamp`	Unix timestamp dell'invio (secondi)
`X-Tikento-Request-Id`	Identificativo univoco della richiesta

Struttura del corpo

{
  "event": "registration.created",
  "timestamp": "2026-06-30T14:30:00Z",
  "requestId": "req_01912345abcdef",
  "data": {
    "id": "01912345-6789-7abc-def0-123456789abc",
    "event_id": "01900000-0000-7000-0000-000000000001",
    "status": "registered",
    "fields": {
      "registrant_email": "user@example.com",
      "first_name": "Ivan",
      "last_name": "Petrov"
    },
    "created_at": "2026-06-30T14:30:00Z"
  }
}

Il campo requestId e presente in ogni webhook. Utilizzatelo per la deduplicazione e quando contattate il supporto.

Esempi di payload per tipo di evento

registration.created

{
  "event": "registration.created",
  "timestamp": "2026-06-30T14:30:00Z",
  "requestId": "req_01912345abcdef",
  "data": {
    "id": "01912345-6789-7abc-def0-123456789abc",
    "event_id": "01900000-0000-7000-0000-000000000001",
    "event_slug": "tech-conference-2026",
    "status": "registered",
    "ticket_definition_id": "01900000-0000-7000-0000-000000000010",
    "fields": {
      "registrant_email": "user@example.com",
      "first_name": "Ivan",
      "last_name": "Petrov",
      "company": "Acme Corp"
    },
    "created_at": "2026-06-30T14:30:00Z"
  }
}

payment.completed

{
  "event": "payment.completed",
  "timestamp": "2026-06-30T14:31:00Z",
  "requestId": "req_01912345abcdf0",
  "data": {
    "id": "01912345-6789-7abc-def0-000000000099",
    "registration_id": "01912345-6789-7abc-def0-123456789abc",
    "amount": 5000,
    "currency": "RUB",
    "method": "card",
    "gateway": "yookassa",
    "idempotency_key": "idem_abc123",
    "completed_at": "2026-06-30T14:31:00Z"
  }
}

event.cancelled

{
  "event": "event.cancelled",
  "timestamp": "2026-06-30T15:00:00Z",
  "requestId": "req_01912345abcdf1",
  "data": {
    "id": "01900000-0000-7000-0000-000000000001",
    "slug": "tech-conference-2026",
    "title": "Tech Conference 2026",
    "cancelled_at": "2026-06-30T15:00:00Z",
    "reason": "Venue unavailable"
  }
}

Verifica della firma

Ogni webhook viene firmato con HMAC-SHA256. La verifica della firma garantisce che la richiesta sia stata inviata da tikento e non da un malintenzionato.

Algoritmo

Ottenete i valori degli header X-Tikento-Timestamp e X-Tikento-Signature.
Formate la stringa per la firma: <timestamp>.<body>, dove body e il raw body della richiesta.
Calcolate l'HMAC-SHA256 di questa stringa con il vostro webhook secret.
Confrontate il risultato con X-Tikento-Signature in formato hex.

Esempio in Node.js

const crypto = require('crypto');

function verifySignature(body, timestamp, signature, secret) {
  const payload = `${timestamp}.${body}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  // Confronto constant-time per la protezione dagli attacchi timing
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Esempio in Python

import hmac
import hashlib

def verify_signature(body: str, timestamp: str, signature: str, secret: str) -> bool:
    payload = f"{timestamp}.{body}"
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Protezione dagli attacchi replay

Verificate X-Tikento-Timestamp: se e piu vecchio di 5 minuti, rifiutate la richiesta. Questo previene il riutilizzo di webhook intercettati.

Politica di ripetizione

Se il vostro endpoint non risponde con HTTP 2xx, tikento riprova l'invio:

Tentativo	Ritardo
1	Immediatamente
2	Dopo 1 minuto
3	Dopo 5 minuti
4	Dopo 30 minuti

Se tutti e 4 i tentativi (iniziale + 3 ripetizioni) falliscono, l'evento viene contrassegnato come failed. Vedrete la lista dei webhook falliti nella sezione Impostazioni - Integrazioni - Cronologia consegne.

Cosa conta come successo

HTTP 200, 201, 202, 204 -- la consegna e considerata riuscita.
Timeout: la risposta deve essere ricevuta entro 10 secondi.

Cosa conta come errore

HTTP 4xx (tranne 410) -- reinvio, possibile problema dal lato del destinatario.
HTTP 5xx -- reinvio con ritardo.
Timeout (nessuna risposta entro 10 secondi) -- reinvio.
HTTP 410 (Gone) -- il webhook viene automaticamente disattivato, nessun reinvio.

Deduplicazione

A causa dei reinvii il vostro endpoint potrebbe ricevere lo stesso evento piu volte. Utilizzate il requestId dal payload per la deduplicazione:

Alla ricezione del webhook verificate se avete gia elaborato quel requestId.
Se si -- restituite HTTP 200 senza rielaborazione.
Se no -- elaborate e salvate il requestId.

Accettate i webhook solo tramite HTTPS.
Verificate sempre la firma tramite HMAC-SHA256.
Verificate il timestamp per la protezione dagli attacchi replay.
Conservate il webhook secret nelle variabili d'ambiente, non nel codice.