api.botsubscription.com

GET/v1/endpoint

AuthenticationBearer

Token

Stays in this tab. Required for this endpoint — the value below is what gets sent.

Path parameters0

Query parameters0

Headers0

BodyJSON

Examples

curl --request GET \
  --url https://api.botsubscription.com/v1/endpoint \
  --header 'Authorization: Bearer sk_live_•••'

Create a Subscription Bot Webhook

Register a new endpoint to receive real-time event notifications from your subscription bot. When payments complete, memberships change, or other events occur, BotSubscription sends HTTP POST requests to your specified URL with event details and a signature for verification.

POST/v2/projects/{project_id}/integrations/webhooks

Authorization

Bearer API KeyRequired

API key scope: webhooks:create (required for restricted keys).

Each project is capped at 10 webhook endpoints; the endpoint returns 409 when that limit is reached, and also rejects a second endpoint that reuses an existing URL with 409. The secret is returned only on creation—store it immediately to verify incoming signatures.

Retries: save the first successful response. A completed request made with Idempotency-Key cannot replay its signing secret and returns 409 IDEMPOTENCY_RESPONSE_NOT_REPLAYABLE. Reconcile registration state before starting another creation attempt.

Register endpoints with HTTPS, including during development. Localhost, loopback, private and reserved addresses are blocked, including hostnames resolving to them. See webhook receiver requirements.

Path Parameters

project_idstringrequired

The unique identifier of the project.

Request Body

urlstringrequired

The final, publicly reachable HTTPS URL for webhook events. Redirects are not followed.

curl -X POST "https://api.botsubscription.com/v2/projects/YOUR_PROJECT_ID/integrations/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.com/webhooks/botsubscription"
  }'

const project_id = 'YOUR_PROJECT_ID';
const response = await fetch(`https://api.botsubscription.com/v2/projects/${project_id}/integrations/webhooks`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://myapp.com/webhooks/botsubscription'
  })
});
const data = await response.json();

import requests
 
project_id = 'YOUR_PROJECT_ID'
response = requests.post(
    f'https://api.botsubscription.com/v2/projects/{project_id}/integrations/webhooks',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={'url': 'https://myapp.com/webhooks/botsubscription'}
)
data = response.json()

$project_id = 'YOUR_PROJECT_ID';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.botsubscription.com/v2/projects/{$project_id}/integrations/webhooks");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'url' => 'https://myapp.com/webhooks/botsubscription'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

Webhook createdapplication/json

{
  "ok": true,
  "request_id": "11111111-1111-1111-1111-111111111111",
  "method": "POST",
  "path": "/v2/projects/11111111-1111-4111-8111-111111111111/integrations/webhooks",
  "code": 200,
  "message": "Webhook created successfully",
  "data": {
    "url": "https://myapp.com/webhooks/botsubscription",
    "id": "22222222-2222-2222-2222-222222222222",
    "secret": "a1b2c3d4e5f6..."
  }
}

Invalid webhook URLapplication/json

{
  "ok": false,
  "request_id": "44444444-4444-4444-8444-444444444444",
  "method": "POST",
  "path": "/v2/projects/11111111-1111-4111-8111-111111111111/integrations/webhooks",
  "code": 422,
  "errors": [
    {
      "message": "body: url Invalid webhook URL",
      "error_code": "VALIDATION_ERROR"
    },
    {
      "message": "body: url Invalid URL format",
      "error_code": "VALIDATION_ERROR"
    }
  ]
}

Webhook URL already registeredapplication/json

{
  "ok": false,
  "request_id": "44444444-4444-4444-8444-444444444444",
  "method": "POST",
  "path": "/v2/projects/11111111-1111-4111-8111-111111111111/integrations/webhooks",
  "code": 409,
  "error": {
    "error_code": "CONFLICT",
    "message": "Webhook URL already exists"
  }
}

Completed secret response cannot be replayedapplication/json

{
  "ok": false,
  "request_id": "44444444-4444-4444-8444-444444444444",
  "method": "POST",
  "path": "/v2/projects/11111111-1111-4111-8111-111111111111/integrations/webhooks",
  "code": 409,
  "error": {
    "error_code": "IDEMPOTENCY_RESPONSE_NOT_REPLAYABLE",
    "message": "A request with this Idempotency-Key was already processed, but its response cannot be replayed"
  }
}

Invalid or expired API keyapplication/json

{
  "ok": false,
  "request_id": "44444444-4444-4444-8444-444444444444",
  "method": "POST",
  "path": "/v2/projects/11111111-1111-4111-8111-111111111111/integrations/webhooks",
  "code": 401,
  "error": {
    "message": "Invalid or expired authentication token.",
    "error_code": "UNAUTHORIZED"
  }
}

Last updated: November 4, 2026