Webhook Endpoints

Manage where ZaroPay sends event notifications. You can also do all of this in the dashboard.

The signing secret is shown once

Creating an endpoint returns its secret (whsec_…) exactly once. Store it — you'll need it to verify signatures. It can only be rotated, never re-read.

Create POST /v1/webhooks/endpoints

Field	Type	Notes
url	string	Required. http/https, max 2048. SSRF-guarded (422 INVALID_WEBHOOK_URL for private/loopback unless explicitly allowed).
description	string | null	max 255
eventTypes	string[]	Optional; defaults to ["deposit.confirmed"]. An unsupported name fails validation → 422 "Validation failed" with details[].field = "eventTypes.<index>".

Returns the endpoint row with secret revealed once:

{
  "success": true,
  "message": "Created",
  "data": {
    "id": "…", "url": "https://shop.example.com/webhooks/zaropay",
    "event_types": ["deposit.confirmed"], "status": "active", "is_active": true,
    "secret": "whsec_0123…64hex", "created_at": "…"
  }
}

List GET /v1/webhooks/endpoints

Query: status, page, limit. Returns endpoint rows (without secret) + meta.

Retrieve GET /v1/webhooks/endpoints/:id

Returns one endpoint row (no secret).

Update PATCH /v1/webhooks/endpoints/:id

At least one of: url, description, eventTypes (min 1), isActive (boolean → toggles active/disabled). Returns the updated row.

Delete DELETE /v1/webhooks/endpoints/:id

Soft-deletes the endpoint and its secret. Returns { "id": "…", "deleted": true }.

Send a test event POST /v1/webhooks/endpoints/:id/test

Delivers a signed webhook.test event to the saved endpoint. Returns { "ok": boolean, "statusCode"?: number, "durationMs"?: number, "error"?: string } — durationMs is omitted when the URL is rejected before any request is made.

Delivery logs

• GET /v1/webhooks/deliveries — query status, referenceId (the depositId), page, limit. Each row: event_type, reference_id, status (PENDING/SENDING/DELIVERED/FAILED/EXHAUSTED), attempts, last_status_code, last_error, next_attempt_at, timestamps.
• GET /v1/webhooks/deliveries/:id — the delivery row plus an attempts[] array with per-try status_code, response snippet, error, duration_ms, attempted_at.

Use these to debug delivery from your side without adding logging.