Skip to main content

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​

FieldTypeNotes
urlstringRequired. http/https, max 2048. SSRF-guarded (422 INVALID_WEBHOOK_URL for private/loopback unless explicitly allowed).
descriptionstring | nullmax 255
eventTypesstring[]Optional; defaults to ["deposit.confirmed"]. Unsupported name → 422 INVALID_EVENT_TYPE.

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 }.

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.