¿Qué planes soportan webhooks?

Los webhooks están disponibles en los planes Pro, Business y Enterprise. En el plan gratuito los webhooks no están disponibles -- use la exportación manual o la API pública.

¿Cuántas veces reintenta tikento el envío en caso de error?

Tres intentos con retardo exponencial: a los 1 minuto, 5 minutos y 30 minutos. Si los tres intentos fallan, el evento se marca como failed.

¿Cómo verificar la firma del webhook?

Calcule el HMAC-SHA256 del cuerpo de la solicitud con su webhook secret y compárelo con el encabezado X-Tikento-Signature. Use comparación en tiempo constante para protección contra ataques de temporización.

¿Se pueden configurar varias URLs para webhooks?

Sí. En la sección Configuración - Integraciones puede agregar varias URLs y elegir qué tipos de eventos enviar a cada una.

Webhooks: eventos y verificación de firma

Descripción general

Los webhooks permiten recibir notificaciones sobre eventos en la plataforma tikento en tiempo real. Cuando ocurre un evento (nuevo registro, pago exitoso, cancelación de evento), tikento envía una solicitud HTTP POST a su URL con los datos del evento.

Los webhooks están disponibles en los planes Pro, Business y Enterprise.

Configuración

Agregar URL de webhook

Abra Configuración en el menú lateral.
Vaya a la sección «Integraciones».
Haga clic en «Agregar webhook».
Indique la URL del endpoint (HTTPS obligatorio).
Seleccione los tipos de eventos que desea recibir.
Haga clic en «Guardar».

Después de guardar, tikento enviará una solicitud de prueba a la URL indicada para verificar la disponibilidad.

Webhook secret

Al crear el webhook, el sistema generará un webhook secret -- una cadena para verificación de firma. Guárdelo en un lugar seguro. El secret se muestra solo una vez.

Tipos de eventos

Evento	Descripción
`registration.created`	Se creó un nuevo registro
`registration.updated`	Se actualizaron datos del registro (estado, campos)
`payment.completed`	Pago completado exitosamente
`payment.refunded`	Se realizó un reembolso
`event.published`	Evento publicado
`event.cancelled`	Evento cancelado

Puede suscribirse a todos los tipos o seleccionar solo los necesarios en la configuración de integraciones.

Formato del payload

Cada webhook se envía como HTTP POST con cuerpo en formato JSON.

Encabezados de la solicitud

Encabezado	Descripción
`Content-Type`	`application/json`
`X-Tikento-Event`	Tipo de evento (por ejemplo, `registration.created`)
`X-Tikento-Signature`	Firma HMAC-SHA256 del cuerpo de la solicitud
`X-Tikento-Timestamp`	Unix timestamp del envío (segundos)
`X-Tikento-Request-Id`	Identificador único de la solicitud

Estructura del cuerpo

{
  "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"
  }
}

El campo requestId está presente en cada webhook. Úselo para deduplicación y al contactar a soporte.

Ejemplos de payload por tipo de 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"
  }
}

Verificación de firma

Cada webhook se firma mediante HMAC-SHA256. La verificación de firma garantiza que la solicitud fue enviada por tikento y no por un atacante.

Algoritmo

Obtenga los valores de los encabezados X-Tikento-Timestamp y X-Tikento-Signature.
Forme la cadena para firmar: <timestamp>.<body>, donde body es el raw body de la solicitud.
Calcule el HMAC-SHA256 de esta cadena con su webhook secret.
Compare el resultado con X-Tikento-Signature en formato hex.

Ejemplo en 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');

  // Comparación en tiempo constante para protección contra ataques de temporización
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Ejemplo en 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)

Protección contra ataques de repetición

Verifique X-Tikento-Timestamp: si tiene más de 5 minutos -- rechace la solicitud. Esto previene la reutilización de webhooks interceptados.

Política de reintentos

Si su endpoint no responde con HTTP 2xx, tikento reintenta el envío:

Intento	Retardo
1	Inmediatamente
2	Después de 1 minuto
3	Después de 5 minutos
4	Después de 30 minutos

Si los 4 intentos (el inicial + 3 reintentos) fallan, el evento se marca como failed. Verá la lista de webhooks fallidos en la sección Configuración - Integraciones - Historial de entrega.

Qué se considera éxito

HTTP 200, 201, 202, 204 -- la entrega se considera exitosa.
Timeout: la respuesta debe recibirse en 10 segundos.

Qué se considera error

HTTP 4xx (excepto 410) -- reenvío, posible problema del lado del receptor.
HTTP 5xx -- reenvío con retardo.
Timeout (sin respuesta en 10 segundos) -- reenvío.
HTTP 410 (Gone) -- el webhook se desactiva automáticamente, no habrá reintentos.

Deduplicación

Debido a los reintentos, su endpoint puede recibir el mismo evento varias veces. Use requestId del payload para deduplicación:

Al recibir el webhook, verifique si ya procesó ese requestId.
Si es así -- devuelva HTTP 200 sin procesamiento repetido.
Si no -- procese y guarde el requestId.

Acepte webhooks solo por HTTPS.
Siempre verifique la firma mediante HMAC-SHA256.
Verifique el timestamp para protección contra ataques de repetición.
Almacene el webhook secret en variables de entorno, no en el código.