Skip to main content
Bondify sends a webhook POST request to your configured endpoint each time a user completes or abandons a login flow. Every request body is a JSON object with an event field that identifies the event type, plus event-specific fields described below. Before acting on any payload, always verify the X-Bondify-Signature header to confirm the request genuinely originated from Bondify.

​
auth.confirmed

Bondify fires auth.confirmed as soon as a user taps ✅ Confirm inside the Telegram bot. This is the signal to consider the user authenticated — create their session, set a cookie, or push a notification to your frontend. 
{
  "event": "auth.confirmed",
  "session_token": "sess_abc123",
  "telegram_id": "123456789",
  "telegram_name": "Alex Johnson",
  "telegram_username": "alexj",
  "confirmed_at": 1700000000000
}
​
event
string
required
Always "auth.confirmed". Use this field to route the event in your handler.
​
session_token
string
required
The session token that was confirmed. Matches the token you received from /api/v1/generate/public when you created the login request.
​
telegram_id
string
required
The user’s unique Telegram account ID. This value is stable across logins and safe to use as a primary user identifier.
​
telegram_name
string
required
The user’s display name as set in their Telegram profile (e.g. "Alex Johnson").
​
telegram_username
string | null
required
The user’s Telegram @handle without the @ prefix (e.g. "alexj"). This field is null when the user has not set a username in Telegram.
​
confirmed_at
number
required
Unix timestamp in milliseconds recording when the user tapped Confirm.

​
auth.cancelled

Bondify fires auth.cancelled when a user taps ❌ Cancel inside the Telegram bot, explicitly declining the login request. Use this event to notify your frontend so it can stop any loading state and display an appropriate message. 
{
  "event": "auth.cancelled",
  "session_token": "sess_abc123",
  "cancelled_at": 1700000000000
}
​
event
string
required
Always "auth.cancelled". Use this field to route the event in your handler.
​
session_token
string
required
The session token that was cancelled. Use this to look up and invalidate any pending login attempt in your system.
​
cancelled_at
number
required
Unix timestamp in milliseconds recording when the user tapped Cancel.

​
Handling events in code

The example below shows a minimal Express handler that verifies the signature and branches on both event types. See Webhook Verification for a deeper look at the signature check. 
import crypto from 'crypto';
import express from 'express';

const app = express();

// Use express.raw() to capture the raw body before JSON parsing
app.post('/webhooks/bondify', express.raw({ type: '*/*' }), (req, res) => {
  // 1. Verify signature using the raw request body (see Webhook Verification)
  const sig = req.headers['x-bondify-signature'] as string;
  const rawBody = req.body.toString();
  const expected = crypto
    .createHmac('sha256', process.env.BONDIFY_SECRET_KEY!)
    .update(rawBody)
    .digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).end();
  }

  // 2. Parse and handle events
  const payload = JSON.parse(rawBody);
  const { event } = payload;
  if (event === 'auth.confirmed') {
    // Log user in, notify frontend via WebSocket, etc.
    console.log('User confirmed:', payload.telegram_id);
  } else if (event === 'auth.cancelled') {
    // Notify frontend
    console.log('User cancelled session:', payload.session_token);
  }

  res.status(200).end();
});
Always verify the X-Bondify-Signature header before reading or acting on any event payload. Processing unverified requests exposes your application to spoofed events that could create fraudulent sessions.