Webhooks
Webhook — HTTP-запрос, который сервис ОТПРАВЛЯЕТ тебе при событии. Альтернатива polling. GitHub при push шлёт POST на твой URL, Stripe при оплате — POST на твой URL.
Как работает
- Ты регистрируешь URL в сервисе (Settings → Webhooks).
- Указываешь на какие события подписан (push, invoice.paid).
- Сервис при событии шлёт POST /твой-url с JSON.
- Ты отвечаешь 2xx = принял. 5xx = сервис повторит.
Пример GitHub push
POST /webhook-endpoint HTTP/1.1
Host: yourapp.com
X-GitHub-Event: push
X-GitHub-Delivery: 12345-uuid
X-Hub-Signature-256: sha256=abcdef...
Content-Type: application/json
{
"ref": "refs/heads/main",
"commits": [...],
"repository": {...}
}Безопасность
1. HMAC-подпись
Сервис подписывает body секретом. Ты вычисляешь HMAC и сверяешь.
# github
X-Hub-Signature-256: sha256=<HMAC-SHA256(secret, body)>
# stripe
Stripe-Signature: t=1700000000,v1=<hash>2. Whitelist IP
GitHub, Stripe публикуют список IP-адресов с которых шлют.
3. Timestamp
В подписи включён timestamp → защита от replay.
Идемпотентность
Сервис может повторить webhook (5xx, timeout). Твой обработчик должен быть idempotent — обрабатывать delivery_id один раз (см. idempotency).
Retries
- Stripe: до 3 суток, exponential backoff
- GitHub: до 8 раз с backoff
- Twilio: до 24 часов
Проблемы webhook
- Нужен public HTTPS-URL (проблема dev — решается ngrok, localtunnel, cloudflared)
- Никакой backpressure — если ты медленный, события копятся у отправителя
- Порядок не гарантирован (без sequence numbers)
Альтернативы
- Polling — сам опрашивай API. Просто, но затратно
- SSE / WebSocket — сервис держит соединение с тобой
- Message queue — Kafka, SQS, RabbitMQ
Dev-инструменты
- webhook.site — просмотр входящих
- ngrok, cloudflared tunnel — пробросить localhost
- Svix, Hookdeck — SaaS для приёма и retries