Webhook guide

When to use

Use webhooks when your bot endpoint is publicly reachable. For local dev without a public URL, use long polling.

Steps

1. Expose an https:// endpoint (self-signed certs usually fail).
2. Set URL + secret_token in the console or via POST /api/v1/bots/setWebhook.
3. Verify V2 signature: X-StarIM-Signature-V2 + X-StarIM-Timestamp over timestamp + "." + rawBody. Use X-StarIM-Update-Id for idempotency (±300s skew in the official SDK).
4. Confirm deliveries in the console Delivery logs panel.

Example

curl -X POST "$API/bots/setWebhook" \
  -H "Authorization: Bearer $SOCHAT_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hook","secret_token":"your-secret"}'

Limits & errors

• Conflicts with getUpdates → 409 while a webhook is active.
• 15s timeout; retries 1m/5m/15m/1h then dead_letter.
• Egress IPs: getWebhookInfo.platform_egress_ips.

Next

Webhook APIs · Updates.