Webhooks

Webhooks are optional signed notifications to your HTTPS receiver. Polling remains available, and customers do not need to install a webhook to use the API.

My API account

Enable the receiver in your API account. Public HTTPS on port 443 is required; redirects, query strings and URL credentials are not supported. Changes to URL, enablement or signing secret cancel old pending events. Historical operations are not backfilled.

Only supported new API operations are observed, not every HTTP response or website purchase. Notifications contain safe identifiers and state, never API keys or proxy passwords. timestamp records local UTC observation; the minute worker may introduce delay.

Event types

Type	State
`webhook.test`	`test`
`order.accepted`	`accepted`
`order.delivered`	`delivered`
`order.action_required`	`action_required`
`order.canceled`	`canceled`
`renewal.completed`	`completed`
`extra_login.operation.completed`	`completed`
`extra_login.operation.rejected`	`rejected`
`extra_login.operation.action_required`	`action_required`
`proxy_ip.operation.completed`	`completed`
`proxy_ip.operation.rejected`	`rejected`
`proxy_ip.operation.action_required`	`action_required`
`proxy_ip.authorization.revoked`	`revoked`
`residential_list.operation.completed`	`completed`
`residential_list.operation.rejected`	`rejected`
`residential_list.operation.action_required`	`action_required`
`auto_renewal.configuration.completed`	`completed`

application/json

{
    "id": "evt_0123456789abcdef0123456789abcdef",
    "type": "order.delivered",
    "timestamp": "2026-10-26T12:00:00+00:00",
    "api_version": "1",
    "data": {
        "account_id": 12345,
        "order_id": 12345,
        "number": "1000012345",
        "product": "proxy",
        "state": "delivered",
        "quantity": 1,
        "mode": null,
        "gb": null,
        "reason_code": null,
        "provider_live_check": false
    }
}

Signature verification

Verify webhook-id, webhook-timestamp and webhook-signature using the separate webhook secret. Remove whsec_, Base64-decode the key, sign the exact raw body framing below with HMAC-SHA256, and compare in constant time. Enforce a 300-second timestamp tolerance.

HMAC-SHA256

signed_content = webhook_id + "." + webhook_timestamp + "." + raw_body
webhook_signature = "v1," + Base64(HMAC_SHA256(decoded_secret, signed_content))

Delivery & retries

Process each event ID idempotently. Delivery can repeat and arrive out of order. Return 2xx after accepting it. At most 7 attempts use delays of 1 min, 5 min, 30 min, 2 h, 6 h and 24 h. Retries resend only the notification, never the business operation.

HTTP 2xx confirms delivery. HTTP 408/429/5xx and transient network failures may retry. Other 4xx and redirects fail permanently. Retry attempts keep the same event ID and body with a new signing timestamp.