POST
Create a webhook endpoint

Authorizations

Authorization
string
header
default:sk_test_docs_246e232c64ccc7a001bf61ec0f2e6ab0
required

Authorization: Bearer <secret key>. Secret keys belong to your organisation, are shown once when created in the dashboard, and are scoped (see x-required-scope on each operation). Keep them on your server. Live keys are issued after your business is verified. Publishable keys (pk_) are only for @ketapay/checkout and don't work here.

Headers

Idempotency-Key
string
required

Unique key for this operation. Retries with the same key return the first result.

Maximum string length: 255
Example:

"7f3e2a10-6c4d-4b8e-9a1f-2d5c8e7b6a40"

Body

application/json
url
string<uri>
required
Pattern: ^https://
enabled_events
(enum<string> | string)[]

Event types to send, or ["*"] for all, including types added later. Leave it out to receive every event.

Minimum array length: 1

New event types may be added. Ignore types you don't handle.

Available options:
checkout_session.expired,
escrow.funded,
milestone.delivered,
milestone.released,
escrow.completed,
escrow.refunded,
dispute.opened,
dispute.evidence_requested,
dispute.evidence_submitted,
dispute.resolved,
payout.sent,
refund.sent,
refund.failed,
chargeback.opened,
chargeback.closed,
payout.failed
description
string | null
Maximum string length: 200
metadata
object

Your own key-value pairs. KetaPay stores them and never reads them.

Example:

Response

Webhook endpoint created; secret is shown this once

id
string<uuid>
required
object
string
required
Allowed value: "webhook_endpoint"
livemode
boolean
required
url
string<uri>
required
enabled_events
string[]
required
description
string | null
required
status
enum<string>
required

failing: deliveries have failed for 3 days; fix the endpoint and re-enable it in the dashboard.

Available options:
enabled,
failing,
disabled
metadata
object
required

Your own key-value pairs. KetaPay stores them and never reads them.

Example:
created_at
string<date-time>
required
secret
string
required

Signing secret. Shown only in this response.

Example:

"whsec_9f8c1e2d7b6a5f4e3d2c1b0a9f8e7d6c"