Webhooks turn Telegram conversations and CRM events into workflows, but they also create an internet-facing command surface. A public endpoint that merely checks a secret query parameter is not enough.
The design goal is authenticity, integrity, freshness, reliability, and traceability without making the sender wait for downstream business logic.
Architecture decision
A secure webhook consumer verifies a cryptographic signature over the unmodified request body, rejects stale or replayed deliveries, records a unique delivery ID, acknowledges quickly, processes asynchronously, retries idempotently, and preserves an auditable outcome for every accepted event.
Design requirements
- A reference verification sequence.
- Replay and duplicate-delivery controls.
- Queue and retry boundaries.
- A production readiness checklist.
Verify before parsing or acting
The exact signature scheme must follow the provider documentation. Never invent field ordering or verify a reconstructed JSON object when the protocol signs the raw body.
| Step | Control | Failure response |
|---|---|---|
| 1 | Read the raw request bytes | Do not normalize or reserialize first |
| 2 | Extract signature, timestamp, and delivery ID | Reject missing required headers |
| 3 | Check timestamp inside a narrow tolerance | Reject stale deliveries |
| 4 | Compute HMAC with the endpoint secret | Use constant-time comparison |
| 5 | Check delivery ID store | Acknowledge known duplicates without repeating effects |
| 6 | Parse and validate the event schema | Quarantine unknown or invalid payloads |
Separate receipt from processing
- Persist the verified envelope and enqueue it.
- Return a success response within the provider's timeout.
- Process business actions in a worker with bounded retries.
- Send permanent failures to a dead-letter queue.
- Expose replay tooling that requires authorization and records the operator.
Make every handler idempotent
Networks retry. Providers retry. Operators replay. Assume the same event will arrive more than once. Use the delivery ID or a stable event key as a uniqueness boundary, and make downstream writes conditional on the current state.
A 200 response is not business success
It only means the receiver accepted responsibility. Track queued, processed, ignored, retried, and dead-lettered outcomes separately.
Rotate and scope secrets
- Use a different secret per endpoint or environment.
- Store secrets in a managed secret store, not source code or logs.
- Support overlapping old and new keys during a short rotation window.
- Redact payload fields and authorization material from observability tools.
- Revoke the endpoint immediately when exposure is suspected.
Production checklist
| Area | Evidence |
|---|---|
| Authenticity | Valid and invalid signature tests |
| Freshness | Expired timestamp and replay tests |
| Reliability | Duplicate, timeout, retry, and dead-letter tests |
| Schema | Versioning and unknown-event behavior |
| Operations | Metrics, alerting, reprocessing, and owner |
| Privacy | Minimal payload retention and documented deletion |
Research note
The architecture follows established webhook and secrets-management guidance. Implement the exact algorithm, headers, and retry semantics documented by your provider.
Build the safe path first
The safe webhook pattern is simple to describe and easy to get subtly wrong. Verify raw bytes, reject replays, decouple work, design idempotency, and make every delivery explainable.
Connect TeleBoost events to your stack
TeleBoost provides signed webhooks alongside its REST API and hosted MCP server, with scoped access designed for controlled automation.
Continue the operating system
Related TeleBoost guides
Evidence base