ProBusinessEnterprise

Webhooks: events and signature verification

Overview

Webhooks allow you to receive notifications about events on the tikento platform in real time. When an event occurs (new registration, successful payment, event cancellation), tikento sends an HTTP POST request to your URL with the event data.

Webhooks are available on Pro, Business, and Enterprise plans.

Setup

Adding a webhook URL

  1. Open Settings in the sidebar menu.
  2. Go to the "Integrations" section.
  3. Click "Add webhook".
  4. Enter the endpoint URL (HTTPS required).
  5. Select the event types you want to receive.
  6. Click "Save".

After saving, tikento will send a test request to the specified URL to verify availability.

Webhook secret

When creating a webhook, the system generates a webhook secret -- a string for signature verification. Save it in a secure location. The secret is shown only once.

Event types

EventDescriptionPlans
registration.createdNew registration createdPro, Business, Enterprise
registration.updatedRegistration status changed (moderation, cancellation)Pro, Business, Enterprise
payment.completedPayment successfully completedPro, Business, Enterprise
payment.refundedPayment refundedPro, Business, Enterprise
event.publishedEvent publishedBusiness, Enterprise
event.cancelledEvent cancelledBusiness, Enterprise
checkin.scannedTicket checked in (QR scan or manual)Business, Enterprise
lead.capturedNew lead captured via registration formEnterprise

You can subscribe to all types available on your plan or select only the ones you need.

Limits

ProBusinessEnterprise
Max webhook endpoints31050
Delivery history retention7 days30 days90 days
HTTP timeout per request10 seconds10 seconds10 seconds

Payload format

Each webhook is sent as an HTTP POST with a JSON body.

Request headers

HeaderDescription
Content-Typeapplication/json
X-Tikento-EventEvent type (e.g., registration.created)
X-Tikento-SignatureSignature: t=<unix_ts>,v1=<hmac_hex>
X-Tikento-TimestampUnix timestamp of sending (seconds)
X-Tikento-Request-IdUnique request identifier

Body structure

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

The requestId field is present in every webhook. Use it for deduplication and when contacting support.

Payload examples by event type

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

Signature verification

Each webhook is signed using HMAC-SHA256. Signature verification ensures the request was sent by tikento, not an attacker.

Algorithm

  1. Retrieve the X-Tikento-Signature header. It has the format: t=<unix_timestamp>,v1=<hex_hmac>.
  2. Parse t (timestamp) and v1 (signature) from the header.
  3. Construct the signing string: <t>.<raw_body>.
  4. Compute HMAC-SHA256 of this string with your webhook secret.
  5. Compare the result with v1 using constant-time comparison.
  6. Check that |now - t| < 300 (5 minutes) to prevent replay attacks.

Node.js example

const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, secret) {
  // Parse header: "t=1698300000,v1=abc123..."
  const parts = Object.fromEntries(
    signatureHeader.split(',').map(p => p.split('=', 2))
  );
  const timestamp = parts.t;
  const receivedSig = parts.v1;

  // Check timestamp (reject if older than 5 minutes)
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (age > 300) throw new Error('Webhook timestamp too old');

  // Compute expected signature
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  // Constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(receivedSig)
  );
}

Python example

import hmac
import hashlib
import time

def verify_webhook(raw_body: str, signature_header: str, secret: str) -> bool:
    # Parse header: "t=1698300000,v1=abc123..."
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    timestamp = parts["t"]
    received_sig = parts["v1"]

    # Check timestamp (reject if older than 5 minutes)
    age = abs(int(time.time()) - int(timestamp))
    if age > 300:
        raise ValueError("Webhook timestamp too old")

    # Compute expected signature
    payload = f"{timestamp}.{raw_body}"
    expected = hmac.new(
        secret.encode(), payload.encode(), hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, received_sig)

Replay attack protection

Check the X-Tikento-Timestamp: if it is older than 5 minutes, reject the request. This prevents reuse of intercepted webhooks.

Retry policy

If your endpoint does not respond with HTTP 2xx, tikento retries delivery:

AttemptDelay
1Immediately
2After 1 minute
3After 5 minutes
4After 30 minutes

If all 4 attempts (initial + 3 retries) are unsuccessful, the event is marked as failed. You will see a list of failed webhooks in Settings - Integrations - Delivery history.

What counts as success

  • HTTP 200, 201, 202, 204 -- delivery is considered successful.
  • Timeout: a response must be received within 10 seconds.

What counts as an error

  • HTTP 4xx (except 410) -- retry, possible issue on the receiver's side.
  • HTTP 5xx -- retry with delay.
  • Timeout (no response within 10 seconds) -- retry.
  • HTTP 410 (Gone) -- the webhook is automatically disabled, no retries.

Deduplication

Due to retries, your endpoint may receive the same event multiple times. Use requestId from the payload for deduplication:

  1. When receiving a webhook, check if you have already processed this requestId.
  2. If yes -- return HTTP 200 without reprocessing.
  3. If no -- process and save the requestId.

Recommendations

Quick response

Send HTTP 200 immediately upon receiving the request. Perform long-running processing asynchronously (queue, background task). This reduces the risk of timeouts and retries.

Idempotency

Design your handler so that reprocessing the same event does not cause duplicate actions (double email sends, duplicate charges, etc.).

Logging

Save the requestId, X-Tikento-Event, and timestamp of each received webhook. This helps with debugging and when contacting support.

Security

  • Accept webhooks only over HTTPS.
  • Always verify the signature via HMAC-SHA256.
  • Check the timestamp for replay attack protection.
  • Store the webhook secret in environment variables, not in code.

Частые вопросы

Which plans support webhooks?
Webhooks are available on Pro, Business, and Enterprise plans. On the free plan, webhooks are not available -- use manual export or the public API.
How many times does tikento retry delivery on error?
Three retries with exponential backoff: after 1 minute, after 5 minutes, after 30 minutes. If all three retries fail, the event is marked as failed.
How do I verify a webhook signature?
Parse the X-Tikento-Signature header (format: t=<timestamp>,v1=<hex>). Compute HMAC-SHA256 of '<timestamp>.<body>' with your secret. Compare with v1 using constant-time comparison. Reject if timestamp is older than 5 minutes.
Can I configure multiple webhook URLs?
Yes. In Settings - Integrations, you can add multiple URLs and choose which event types to send to each one.