Create a webhook endpoint

POST/v1/webhook_endpointsscope webhooks:manage

The response carries the signing secret (whsec_…) once: verify every delivery's ZyloPay-Signature with it. Up to 16 endpoints per mode.

Body parameters

urlstringrequired: Where to POST events. https is required for live mode (http is allowed in test mode). Private, loopback and link-local addresses are refused. Up to 2048 characters.
enabled_eventsarray of stringsrequired: Event types to receive: exact types, families such as payment_intent.*, or * for all. Available: payment.succeeded, payment.refunded, payment_intent.created, payment_intent.requires_action, payment_intent.processing, payment_intent.succeeded, payment_intent.payment_failed, payment_intent.canceled, refund.created, refund.succeeded, refund.failed, terminal.created, terminal.deactivated, terminal.deleted, kyb.status_changed.
descriptionstring: Up to 500 characters.
api_versionstring: Version of the event payloads. Defaults to the latest.

Headers

ZyloPay-Versionstring: Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.
Idempotency-Keystring: Recommended. A unique key per operation (a UUID v4); retries with the same key and body return the first response.

Returns

HTTP 201 with the webhook endpoint object.

Errors

Status	Meaning
`400`	Invalid request (`invalid_request_error` / `idempotency_error`).
`401`	Missing, invalid, expired or revoked API key (`authentication_error`).
`403`	The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).
`409`	Conflict: idempotency key reused or in progress, or the object is in the wrong state.
`429`	Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.
`500`	Internal error (`api_error`). Retry with the same `Idempotency-Key`.

Branch on error.code. Every code is listed in error codes.

Example request

curl https://zylopay-api.fly.dev/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $ZYLOPAY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/zylopay/webhooks",
    "enabled_events": [
      "payment.succeeded",
      "payment_intent.*",
      "refund.*"
    ],
    "description": "Order service (test)"
  }'

Example response

{
  "id": "we_2Lk9Qm4Xz7Pv1Rt8Wb3Ns6Hd",
  "object": "webhook_endpoint",
  "livemode": false,
  "url": "https://example.com/zylopay/webhooks",
  "description": "Order service (test)",
  "enabled_events": [
    "payment.succeeded",
    "payment_intent.*",
    "refund.*"
  ],
  "status": "enabled",
  "disabled_reason": null,
  "api_version": "2026-09-28",
  "failing_since": null,
  "last_success_at": null,
  "secret_rotation_ends_at": null,
  "created": "2026-09-20T10:00:00.000Z",
  "updated": "2026-09-20T10:00:00.000Z",
  "secret": "whsec_Zx3Kq9Lm2Pw7Rv4Tb8Ns1Hd6Fg5Jc0Ya9Ue2Io3Qp4a"
}

Create a webhook endpoint

Body parametersCopy Anchor Link

HeadersCopy Anchor Link

ReturnsCopy Anchor Link

ErrorsCopy Anchor Link

Example requestCopy Anchor Link