# Webhooks

### Webhook Configuration

Configure webhook endpoints to receive real-time HTTP POST notifications for proxy settings changes and fair usage policy events.

#### Supported Events

| Event                          | Trigger                                                              |
| ------------------------------ | -------------------------------------------------------------------- |
| `proxy_settings.created`       | A new proxy settings request is submitted and awaiting approval      |
| `proxy_settings.approved`      | A proxy settings request has been approved (includes auto-approvals) |
| `proxy_settings.denied`        | A proxy settings request has been denied by an administrator         |
| `proxy_settings.cancelled`     | A proxy settings request has been cancelled                          |
| `sub_user.fair_usage.throttle` | A sub-user's speed was reduced due to fair usage policy              |
| `sub_user.fair_usage.restore`  | A sub-user's speed was restored after traffic returned to normal     |

#### Payload Format

All webhook deliveries are sent as `POST` requests with a JSON body:

```json
{
  "event": "proxy_settings.approved",
  "timestamp": "2024-01-15T10:30:00+00:00",
  "data": { ... }
}
```

#### Signature Verification

Every webhook delivery includes an `X-Webhook-Signature` header containing an HMAC-SHA256 signature. Verify it to ensure the request is authentic:

```
signature = HMAC-SHA256(raw_request_body, webhook_secret)
```

Compare the computed signature against the `X-Webhook-Signature` header value. The `X-Webhook-Event` header also contains the event name for convenience.

#### Delivery Behavior

* **Timeout**: 10 seconds per delivery attempt
* **Retries**: Up to 3 attempts with 30-second backoff between each
* **Success**: Any HTTP 2xx response is considered successful
* **User-Agent**: `PlainProxies-Webhook/1.0`

#### Headers Sent With Each Delivery

| Header                | Description                                 |
| --------------------- | ------------------------------------------- |
| `X-Webhook-Signature` | HMAC-SHA256 signature of the raw JSON body  |
| `X-Webhook-Event`     | Event name (e.g. `proxy_settings.approved`) |
| `Content-Type`        | `application/json`                          |
| `User-Agent`          | `PlainProxies-Webhook/1.0`                  |

## Get webhook settings

> Returns the current webhook configuration for the reseller including the webhook URL and whether a signing secret is configured.

````json
{"openapi":"3.0.0","info":{"title":"PlainProxies API v2","version":"2.0.0"},"tags":[{"name":"Webhooks","description":"## Webhook Configuration\n\nConfigure webhook endpoints to receive real-time HTTP POST notifications for proxy settings changes and fair usage policy events.\n\n### Supported Events\n\n| Event | Trigger |\n|-------|---------|\n| `proxy_settings.created` | A new proxy settings request is submitted and awaiting approval |\n| `proxy_settings.approved` | A proxy settings request has been approved (includes auto-approvals) |\n| `proxy_settings.denied` | A proxy settings request has been denied by an administrator |\n| `proxy_settings.cancelled` | A proxy settings request has been cancelled |\n| `sub_user.fair_usage.throttle` | A sub-user's speed was reduced due to fair usage policy |\n| `sub_user.fair_usage.restore` | A sub-user's speed was restored after traffic returned to normal |\n\n### Payload Format\n\nAll webhook deliveries are sent as `POST` requests with a JSON body:\n\n```json\n{\n  \"event\": \"proxy_settings.approved\",\n  \"timestamp\": \"2024-01-15T10:30:00+00:00\",\n  \"data\": { ... }\n}\n```\n\n### Signature Verification\n\nEvery webhook delivery includes an `X-Webhook-Signature` header containing an HMAC-SHA256 signature. Verify it to ensure the request is authentic:\n\n```\nsignature = HMAC-SHA256(raw_request_body, webhook_secret)\n```\n\nCompare the computed signature against the `X-Webhook-Signature` header value. The `X-Webhook-Event` header also contains the event name for convenience.\n\n### Delivery Behavior\n\n- **Timeout**: 10 seconds per delivery attempt\n- **Retries**: Up to 3 attempts with 30-second backoff between each\n- **Success**: Any HTTP 2xx response is considered successful\n- **User-Agent**: `PlainProxies-Webhook/1.0`\n\n### Headers Sent With Each Delivery\n\n| Header | Description |\n|--------|-------------|\n| `X-Webhook-Signature` | HMAC-SHA256 signature of the raw JSON body |\n| `X-Webhook-Event` | Event name (e.g. `proxy_settings.approved`) |\n| `Content-Type` | `application/json` |\n| `User-Agent` | `PlainProxies-Webhook/1.0` |"}],"servers":[{"url":"https://dashboard.plainproxies.com/api/v2","description":"Production API Server"},{"url":"https://plainproxies-sandbox.com/api/v2","description":"Sandbox API Server"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"API Key authentication. Get your key from the Dashboard Settings page. Include in all requests as: `X-API-KEY: PlainProxies_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`","name":"X-API-KEY","in":"header"}}},"paths":{"/profile/webhook":{"get":{"tags":["Webhooks"],"summary":"Get webhook settings","description":"Returns the current webhook configuration for the reseller including the webhook URL and whether a signing secret is configured.","operationId":"ccb050cad8ec37e369c5c7fbe5f285e5","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"data":{"properties":{"webhook_url":{"description":"The configured webhook URL, or null if not set.","type":"string","format":"uri","nullable":true},"has_secret":{"description":"Whether a webhook secret is configured for signature verification.","type":"boolean"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Unauthorized"},"404":{"description":"User is not a reseller"}}}}}}
````

## Update webhook settings

> Configure or update the webhook endpoint for receiving proxy settings request notifications. Set \`webhook\_url\` to an HTTPS URL to enable webhooks, or \`null\` to disable. Use \`regenerate\_secret\` to generate a new signing secret. The webhook secret is only returned when first created or regenerated — store it securely as it cannot be retrieved later.

````json
{"openapi":"3.0.0","info":{"title":"PlainProxies API v2","version":"2.0.0"},"tags":[{"name":"Webhooks","description":"## Webhook Configuration\n\nConfigure webhook endpoints to receive real-time HTTP POST notifications for proxy settings changes and fair usage policy events.\n\n### Supported Events\n\n| Event | Trigger |\n|-------|---------|\n| `proxy_settings.created` | A new proxy settings request is submitted and awaiting approval |\n| `proxy_settings.approved` | A proxy settings request has been approved (includes auto-approvals) |\n| `proxy_settings.denied` | A proxy settings request has been denied by an administrator |\n| `proxy_settings.cancelled` | A proxy settings request has been cancelled |\n| `sub_user.fair_usage.throttle` | A sub-user's speed was reduced due to fair usage policy |\n| `sub_user.fair_usage.restore` | A sub-user's speed was restored after traffic returned to normal |\n\n### Payload Format\n\nAll webhook deliveries are sent as `POST` requests with a JSON body:\n\n```json\n{\n  \"event\": \"proxy_settings.approved\",\n  \"timestamp\": \"2024-01-15T10:30:00+00:00\",\n  \"data\": { ... }\n}\n```\n\n### Signature Verification\n\nEvery webhook delivery includes an `X-Webhook-Signature` header containing an HMAC-SHA256 signature. Verify it to ensure the request is authentic:\n\n```\nsignature = HMAC-SHA256(raw_request_body, webhook_secret)\n```\n\nCompare the computed signature against the `X-Webhook-Signature` header value. The `X-Webhook-Event` header also contains the event name for convenience.\n\n### Delivery Behavior\n\n- **Timeout**: 10 seconds per delivery attempt\n- **Retries**: Up to 3 attempts with 30-second backoff between each\n- **Success**: Any HTTP 2xx response is considered successful\n- **User-Agent**: `PlainProxies-Webhook/1.0`\n\n### Headers Sent With Each Delivery\n\n| Header | Description |\n|--------|-------------|\n| `X-Webhook-Signature` | HMAC-SHA256 signature of the raw JSON body |\n| `X-Webhook-Event` | Event name (e.g. `proxy_settings.approved`) |\n| `Content-Type` | `application/json` |\n| `User-Agent` | `PlainProxies-Webhook/1.0` |"}],"servers":[{"url":"https://dashboard.plainproxies.com/api/v2","description":"Production API Server"},{"url":"https://plainproxies-sandbox.com/api/v2","description":"Sandbox API Server"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"API Key authentication. Get your key from the Dashboard Settings page. Include in all requests as: `X-API-KEY: PlainProxies_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`","name":"X-API-KEY","in":"header"}},"schemas":{"WebhookUpdateRequest":{"title":"Webhook Update Request","description":"Request body for updating webhook settings. Send `webhook_url` to set or update the webhook endpoint, or send `null` to disable webhooks. Use `regenerate_secret` to generate a new signing secret.","properties":{"webhook_url":{"description":"The HTTPS URL to receive webhook notifications. Set to null to disable webhooks.","type":"string","format":"uri","nullable":true,"maxLength":2048},"regenerate_secret":{"description":"Set to true to generate a new webhook signing secret. The new secret will be returned in the response.","type":"boolean"}},"type":"object"}}},"paths":{"/profile/webhook":{"put":{"tags":["Webhooks"],"summary":"Update webhook settings","description":"Configure or update the webhook endpoint for receiving proxy settings request notifications. Set `webhook_url` to an HTTPS URL to enable webhooks, or `null` to disable. Use `regenerate_secret` to generate a new signing secret. The webhook secret is only returned when first created or regenerated — store it securely as it cannot be retrieved later.","operationId":"84cb129fa0e292c1bc0b6e84dc392ff5","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookUpdateRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"data":{"properties":{"webhook_url":{"type":"string","format":"uri","nullable":true},"has_secret":{"type":"boolean"},"webhook_secret":{"description":"Only returned when the secret is first created or regenerated. Store this securely — it cannot be retrieved again.","type":"string","nullable":true}},"type":"object"}},"type":"object"}}}},"401":{"description":"Unauthorized"},"404":{"description":"User is not a reseller"},"422":{"description":"Validation error"}}}}}}
````


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.plainproxies.com/resller-api-documentation/overview-1/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.