Webhook Events Reference

Before You Begin

You will need:

• A running Tymeslot instance with at least one event type configured
• A publicly accessible HTTPS endpoint to receive webhook deliveries — plain HTTP endpoints are rejected
• A secret token you choose — you will configure it in Tymeslot and verify it on your endpoint to authenticate deliveries

By the end of this guide, you will know how to configure, verify, and consume Tymeslot webhook events in your own application.

1 Add a Webhook

1. In Tymeslot, go to [Dashboard] → [Settings] → [Webhooks] and click [Add Webhook].
2. Enter your HTTPS endpoint URL in the [Endpoint URL] field.
3. Enter a secret token in the [Secret Token] field. Choose a long random string — this is how your endpoint authenticates that deliveries genuinely come from Tymeslot.
4. Click [Save]. Tymeslot immediately sends a test event to verify your endpoint is reachable. Check the [Delivery Logs] tab to see if it was received successfully.

Event Types

Request Headers

Every webhook delivery includes these headers:

X-Tymeslot-Token: <your-configured-secret-token>
Content-Type: application/json
User-Agent: Tymeslot-Webhook/1.0
X-Webhook-ID: <webhook-configuration-id>
X-Delivery-ID: <unique-per-delivery-attempt-id>

Payload Structure

All events use the same envelope. The event field identifies the type; the data field carries the event-specific payload:

{
  "event": "meeting.created",
  "timestamp": "2026-03-01T10:00:00Z",
  "webhook_id": "wh_abc123",
  "data": {
    "meeting": {
      "id": "mtg_xyz789",
      "title": "30-Minute Consultation",
      "start_time": "2026-03-05T14:00:00Z",
      "end_time": "2026-03-05T14:30:00Z",
      "timezone": "Europe/Berlin",
      "status": "confirmed",
      "cancelled_by": null,
      "previous_start_time": null,
      "attendee": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "host": {
        "name": "Alex Johnson",
        "username": "alex"
      },
      "location": {
        "type": "video",
        "url": "https://meet.google.com/abc-defg-hij"
      },
      "urls": {
        "view": "https://tymeslot.yourdomain.com/dashboard/meetings/mtg_xyz789"
      }
    }
  }
}

Verifying the Token

Always compare the X-Tymeslot-Token header against your expected secret before processing any payload. Use a constant-time string comparison — a naive equality check (===) is vulnerable to timing attacks that could allow an attacker to guess your token one character at a time.

Examples in common languages:

// Node.js
const crypto = require('crypto');

function isValidToken(received, expected) {
  const a = Buffer.from(received);
  const b = Buffer.from(expected);
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

# Python
import hmac

def is_valid_token(received: str, expected: str) -> bool:
    return hmac.compare_digest(received, expected)

<?php
// PHP
function is_valid_token(string $received, string $expected): bool {
    return hash_equals($expected, $received);
}

Handling Retries — Idempotency

Because Tymeslot retries failed deliveries, your endpoint may receive the same event more than once. Design your handler to be idempotent — processing the same delivery twice should produce the same result as processing it once.

The simplest approach: store every X-Delivery-ID you successfully process in a database or cache with a short TTL (72 hours covers the full retry window). On each incoming request, check whether the delivery ID was already processed. If it was, return 200 immediately without re-executing the handler logic.

Retry Schedule

A delivery is considered failed when your endpoint returns a non-2xx status code, returns a 3xx redirect, or does not respond within 10 seconds. Failed deliveries are retried on this schedule:

After 5 failed attempts, the delivery is marked as permanently failed. You can manually retry individual deliveries from [Dashboard] → [Settings] → [Webhooks] → [Delivery Logs].

Delivery Logs

The delivery log is your primary debugging tool. To access it:

1. Go to [Dashboard] → [Settings] → [Webhooks].
2. Click [Delivery Logs] next to the webhook you want to inspect.
3. Each row shows the event type, delivery time, HTTP status code your endpoint returned, and the full response body.
4. Click any row to see the complete request payload that was sent.
5. Click [Retry] on a failed delivery to resend it immediately.

When debugging a failed integration, start here — the response body column often shows the exact error your endpoint returned.

Troubleshooting

❓ Frequently Asked Questions

// Node.js
const received = req.headers['x-tymeslot-token'];
const expected = process.env.WEBHOOK_SECRET;
const a = Buffer.from(received ?? '');
const b = Buffer.from(expected);
const valid = a.length === b.length && crypto.timingSafeEqual(a, b);

Verification Checklist

• Webhook added in [Dashboard] → [Settings] → [Webhooks] with an HTTPS endpoint URL and a secret token
• Test event appeared in [Delivery Logs] with a 200 status code
• Your endpoint verifies X-Tymeslot-Token using a constant-time comparison before processing
• Your endpoint stores X-Delivery-ID values and skips reprocessing duplicates
• Your endpoint responds with 200 within 10 seconds (processes slow work asynchronously)
• A real test booking was placed and the meeting.created event arrived at your endpoint with the correct payload
• Your endpoint's SSL certificate is from a public CA (not self-signed)