Webhooks

Reseller webhook endpoint registration management (Phase 3.W.3). The reseller registers to receive a signed POST on an HTTP endpoint on their own server when subscribed events occur (e.g. service.suspended, product.price_changed).

SUBSCRIPTION PATTERNS (event_types):

• * → all events (catch-all)
• prefix.* → namespace wildcard (service., product.) — single segment
• exact → full event name (service.suspended)

VALID EVENTS (V1): service.created, service.suspended, service.unsuspended, service.terminated, product.price_changed, product.stock_changed, product.disabled, credit.added. An unknown event type returns 422.

service.created (Phase 3.W.4): sent when provisioning of the ordered VPS is completed on the Rabisu side and it becomes active (WHMCS domainstatus 'Pending' → 'Active'; detected by cron polling). With this event the reseller learns IMMEDIATELY that the service is ready (GET /orders/{id} polling remains as a fallback). Payload: {provision_id, service_id, order_id, product_id, vps_id, status='active', occurred_at, schema_version}. provision_id = the id in the POST /orders response (reseller correlation key).

credit.added (Phase 3.B): sent when credit is added to the reseller (manual credit by admin or invoice refund). Payload: {reseller_id, amount, currency, reason (manual_credit|refund), description, related_invoice_id, new_balance, occurred_at}. This event goes ONLY to the relevant reseller (not broadcast). Source: WHMCS tblcredit polling (bin/credit-event-emitter.php). NOTE: apply_credit (order payment) does NOT produce this event — it is written in real time by OrderService to the GET /auth/balance/movements audit.

SECRET: The plain HMAC secret in the POST response is shown ONLY once. If lost, the endpoint must be deleted and re-created.

SIGNATURE: The dispatcher adds two headers to every delivery: X-Rabisu-Signature-V2: t=<unix>,v1=<hex> — HMAC-SHA256(secret, "{t}.{X-Rabisu-Event-Type}.{raw body}"). The receiver must verify |now - t| < 300 s and the signed event type (replay + type-swap protection). X-Rabisu-Signature: sha256=<hex> — body only; for legacy receivers, NO replay protection, do not use in new integrations.

CIRCUIT BREAKER: 5 consecutive failed deliveries automatically deactivate the endpoint (is_active=0). The reseller re-activates it with PATCH {is_active: true}.

📄️Register a new webhook endpoint

Registers an HTTP endpoint on the reseller's own server, subscribing it to the selected events. The `secret` plain HMAC secret returned in the response is shown ONLY once.

📄️List the reseller's webhook registrations

Returns ALL endpoints belonging to the reseller (api_key) — including inactive ones (is_active=0, closed by the circuit breaker). So the reseller can see an inactive endpoint and reactivate it via PATCH.

📄️Single webhook detail

Single webhook detail

📄️Partially update a webhook (reactivate / event_types / description)

An unsent field is unchanged (partial update). When `is_active: true` is sent, the endpoint is reactivated and `consecutive_failures` is reset (a clean start for the circuit breaker). If `event_types` is sent, the subscription list is REPLACED entirely (not merged).

📄️Delete a webhook (soft delete)

Soft delete — the record is not removed, `is_active=0` is set (audit + circuit breaker history preserved). The dispatcher no longer delivers to this endpoint.