Webhooks

hooks gives you endpoints at https://<name>.hooks.xvii.network that keep every request.

Create an endpoint

xvii hooks create --name my-bot --verify telegram --secret "$WEBHOOK_SECRET"

Point the provider (Telegram, GitHub, GitLab, Stripe, anything) at https://my-bot.hooks.xvii.network. Each request is kept for the endpoint's retention (7 days by default, up to 90): method, path, headers, the first 1 MB of the body, its size and SHA-256, and the sender.

Receive them on your laptop

xvii hooks listen my-bot --forward 3000
xvii hooks listen my-bot --forward http://localhost:8080/webhook

While listen runs, requests go to your local port and its answer goes back to the sender (within 10 seconds). Your laptop doesn't need to be reachable. Without --forward the requests are only printed and the endpoint answers with its own response. listen rides out network drops and id being briefly away.

Answers

When nobody listens, the endpoint answers with what you set in the panel: status, headers, body and an optional delay. Useful to simulate a slow or failing receiver.

Forwards

Up to five URLs per endpoint. Each request is forwarded and retried after 1 s, 5 s, 30 s, 2 min and 10 min. Private addresses are refused. Every attempt shows as a delivery on the request.

Replay

xvii hooks requests my-bot
xvii hooks replay 3k9x2m7qpa                         # to the listener
xvii hooks replay 3k9x2m7qpa --to forwards
xvii hooks replay 3k9x2m7qpa --to https://example.com/hook

Signatures

With --verify telegram|github|gitlab|stripe and the secret, each request is marked signed or bad. Nothing is refused: hooks is for seeing what arrives. The receiving application must still check signatures itself and be idempotent, because forwards are retried.

Good habits

Use separate endpoints for unrelated projects, with retention that fits.
Don't route OAuth callbacks or payment confirmations through an extra hop just to log them.
Don't send tokens, passwords or full customer payloads to a debugging endpoint.

Limits hooks.endpoints, hooks.storage. Endpoints can get your own names through domains.