Webhook API

The endpoints on this page get, set, delete and test your bot’s webhook. The event format and signature checks are on the Webhooks page.

Get the webhook

GET /v1/me/webhook

{ "url": "https://bot.example.com/sukson", "secret_hint": "Xy9Q", "consecutive_failures": 0 }

Field	Description
url	The current URL, or null when none is set
secret_hint	The secret’s last 4 characters, to tell which secret your server uses
consecutive_failures	Failed deliveries in a row (at the threshold the bot pauses itself, see retries)

Set the webhook

PUT /v1/me/webhook

curl -s -X PUT https://api.sukson.dev/v1/me/webhook \
  -H "Authorization: Bearer $SUKSON_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://bot.example.com/sukson"}'

1. The URL is checked against the URL requirements.
2. A ping event signed with a new secret is sent. Your server must answer 2xx within 10 seconds.
3. The URL is saved and the new secret comes back.

{ "url": "https://bot.example.com/sukson", "secret": "kX2…(43 characters)…Xy9Q", "secret_hint": "Xy9Q" }

• secret is shown once and only when the URL changes. Setting the same URL again gives secret: null and keeps the current secret.
• A new secret changes every person’s sender.id. If you store data keyed by sender.id, plan for that before changing the URL.
• Your signature check must know the new secret before the ping arrives. A safe approach is to accept both the new and the old secret for a while.

HTTP	code	When
422	INVALID_WEBHOOK_URL	The URL can’t be used. details.reason is invalid_url, not_https, credentials_in_url, port_not_allowed, ip_address_host or internal_host.
422	INVALID	No url, or longer than 2,048 characters
422	INVALID	The ping failed (no 2xx within 10 seconds); details.reason is ping_failed and the old URL stays.

Delete the webhook

DELETE /v1/me/webhook

Stops the webhook: the bot gets no events until a URL is set again. Pushing messages still works.

{ "url": null }

Test the webhook

POST /v1/me/webhook/test

Sends a signed ping to the current URL. No body needed (or send {}).

{ "ok": true, "status_category": "http_200", "latency_ms": 184 }

Field	Description
ok	true when your server answered 2xx
status_category	http_<status> when your server answered, otherwise a failure category such as timeout, connect_failed, blocked_address or response_too_large. What your server said is never echoed back.
latency_ms	Time taken, in milliseconds

A bot without a webhook gets 422 INVALID with details.reason no_webhook.