curl --request GET \
--url https://api.botsubscription.com/v1/endpoint \
--header 'Authorization: Bearer sk_live_•••'Verify Subscription Bot Provider Webhook Setup
Read setup instructions for payment-provider notifications to your Telegram subscription bot or Discord subscription bot project. This concerns the provider's connection to BotSubscription. Custom integrations use the separate outbound webhook API.
Authorization
Authorization
Both operations require merchant-accounts:read. Marking verified additionally requires merchant-accounts:update through a human admin's user JWT.
An unrestricted project API key can read status for its project, but receives no signing secret and cannot mark verified (401 UNAUTHORIZED). Restricted project keys cannot use this route (403 FORBIDDEN), regardless of their scopes.
Request body
Send {} or omit the body to retrieve stored or derived status. This does not contact the provider, send a test delivery, or establish that the receiver is reachable.
To override verification for a manual-mode provider:
{ "action": "mark_verified" }This is an administrative override, not proof of delivery. Any required signing credentials must already be configured. Unknown fields, unsupported actions, and action: null return 422 VALIDATION_ERROR.
curl -X POST "https://api.botsubscription.com/v2/projects/YOUR_PROJECT_ID/merchant-accounts/YOUR_ACCOUNT_ID/verify-webhook" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Response and setup controls
Success returns 200 with the standard response envelope and data.merchant_account_id. Normally data also contains:
| Block | Fields |
|---|---|
webhook_verification | required, mode, status, verification_method, verification_supported, can_mark_verified, action_required. |
webhook_setup | For manual providers: required, mode, status, webhook_url, ordered instructions objects (step, text). Optional dashboard_url, missing_credentials, and webhook_secret. |
Verification mode is auto, manual, per_request, or none. Status is pending, verified, or not_required. The verification method is webhook_arrival, signature_check, manual_only, or null. Use the capability fields to decide which controls to offer.
A server-generated webhook_secret is returned only when applicable and available, and only to a human caller with update permission. Treat it as a credential. Project keys never receive it.
Non-manual providers omit webhook_setup, report not_required, and reject the override action. If an override commits but response refresh fails, success may contain only merchant_account_id; the override still took effect. Refresh through the single merchant-account read.
Errors and retries
| Status | Meaning |
|---|---|
401 UNAUTHORIZED | Missing authentication or read/update permission; project key attempting an override. |
403 FORBIDDEN | Restricted-key admission or project-access restriction. |
404 NOT_FOUND | Account or provider not found. |
422 VALIDATION_ERROR | Invalid ID/body, non-manual override, or missing required signing credentials. |
409 CONFLICT | Credentials changed during the operation (reason: "credentials_changed"). Refresh and retry. |
500 SERVER_ERROR | Status or setup could not be read/built. |
Standard project admission, rate-limit, and temporary unavailability errors also apply. An optional Idempotency-Key deduplicates the request, but a completed success is not replayed. Reusing that key returns 409 IDEMPOTENCY_RESPONSE_NOT_REPLAYABLE; refresh account state instead. Preserve the original key and body while recovering an uncertain request.