# BD Event — Telegram webhook

The BD Event Telegram bot receives events through a private webhook. This page documents the endpoint for operators and agents that need to understand the integration.

## Endpoint

`POST https://events.gomievibes.online/api/telegram.php`

## Authentication

Requires a static secret in the header:

```
X-Telegram-Bot-Api-Secret-Token: <configured_secret>
```

- Missing or mismatched secret → `401`.
- The expected secret is read from the site settings (`telegram_webhook_secret`) and compared with `hash_equals`.
- The exact secret is **not published**; operators set it when enrolling the bot's webhook (Telegram's `setWebhook` `secret_token`).

## Payload

Standard Telegram `update` object (`message` / `photo`), e.g.:

```json
{
  "update_id": 123456789,
  "message": {
    "message_id": 10,
    "chat": { "id": 999, "type": "private" },
    "text": "https://example.com/event/abc",
    "from": { "id": 555, "first_name": "A" }
  }
}
```

## Behavior

| Incoming content | Action |
| --- | --- |
| Message containing a URL | Extract event facts (title, date, time, location, registration link) via the same extraction pipeline as the website; store as a submission for admin review |
| Image (photo/document) | Stored as an event flyer |
| Plain text with no URL | Saved as notes |

The bot also sends notifications (new submission, new subscription) into the internal Telegram channel.

## Responses

- `200` — webhook acknowledged (payload processed or intentionally skipped, e.g. duplicate).
- `401` — bad secret.
- `500` — server error (logged).

## Security notes

- The endpoint is **not** part of the public catalog API; do not attempt to guess the secret.
- The webhook accepts only the configured bot's traffic; operators revoke by rotating `telegram_webhook_secret`.

## Related

- [API reference](api.md) — public community/submission/subscription endpoints.
- [Authentication](auth.md) — CSRF/session model for the public API.
- [Contact](/contact) — for operator questions.