Skip to main content
Instead of continuously polling /api/v1/verify/public to check whether a user has acted on a login request, you can configure a webhook endpoint and let Bondify push auth events directly to your server the moment they happen. When a user taps ✅ Confirm or ❌ Cancel in Telegram, Bondify fires a signed HTTP POST request to your URL with a JSON payload describing the event — no polling loop required.

​
Configure your webhook URL

To start receiving events, register your endpoint in the Bondify dashboard:
1

Open your project settings

In the Bondify dashboard, navigate to your project and open the Settings tab.
2

Enter your webhook URL

Paste your publicly reachable HTTPS endpoint into the Webhook URL field (for example, https://yourapp.com/webhooks/bondify).
3

Save changes

Click Save. Bondify will immediately begin sending signed JSON POST requests to that URL for every auth event on this project.

​
Endpoint requirements

Your webhook endpoint must satisfy the following conditions for Bondify to consider a delivery successful:
  • Accept POST requests with Content-Type: application/json
  • Return a 2xx HTTP status code within 10 seconds of receiving the request
  • Verify the X-Bondify-Signature header on every incoming request before processing the payload — see Webhook Verification
If your endpoint returns a non-2xx status or does not respond within 10 seconds, Bondify treats the delivery as failed and will retry it automatically.

​
Supported events

Bondify currently delivers the following webhook events:
EventTrigger
auth.confirmedUser tapped ✅ Confirm in the Telegram bot
auth.cancelledUser tapped ❌ Cancel in the Telegram bot
For full payload schemas and field descriptions, see the Events reference.

​
Retry policy

When a delivery fails — because your endpoint returned a non-2xx response or did not reply within the 10-second window — Bondify automatically retries the request up to 3 times using exponential backoff between attempts.
Webhooks on the Pro plan receive priority delivery with enhanced retry handling, giving your infrastructure more time to recover during brief outages.
Your endpoint should be idempotent: use session_token as a deduplication key so that processing the same event twice does not create duplicate side effects.

​
Testing locally

Before deploying to production, you need a publicly reachable URL to receive test events. Two popular options for exposing a local server are:
Use a tunneling tool like ngrok or Cloudflare Tunnel to expose your local server, or use webhook.site to inspect live payloads without writing any code. Svix Play also provides a free webhook debugger with request history.

​
Webhooks are optional

If you prefer a simpler integration without managing an HTTPS endpoint, you can skip webhooks entirely and poll the /api/v1/verify/public endpoint from your backend at regular intervals until the session reaches a terminal status (confirmed, cancelled, or expired).
Webhooks are entirely optional. Polling /api/v1/verify/public every 2 seconds is a fully supported alternative and works well for lower-traffic applications.