Looking for ePay classic docs? Go to docs.epay.dk
ePay documentationDocsePay documentation
Webhooks

Create Webhook

OpenAPI Spec

Test this endpoint live

Open the same request directly in API Explorer.

Open in API Explorer

Server URL

POST
/public/api/v1/webhooks

Registers a new webhook endpoint limited to domains already approved on your point of sale configuration.

A maximum of 10 active webhooks is allowed per merchant. Each webhook must subscribe to one or more supported events and include a shared secret used as the value of the Authorization header when sending webhook.

Webhooks that fail more than 50% of the time during the previous week will automatically be paused with reason ERROR_RATE_TOO_HIGH. This helps ensure stable operation by minimizing excessive webhook retries.

Webhooks are not required

Webhooks are separate from the main payment flow and act as a general event notification system. You should use them only if you need to track changes to your ePay data in a system that is different from the one initiating the request.

For all payment-related operations, you should use the notificationUrl provided in each request. This is the primary mechanism for receiving the outcome of a payment or operation.

Authorization

BearerAuth
AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Keystring

Ensures that a request can be safely retried without causing duplicate operations. Typically used for actions like payment creation and operations such as refund and void to prevent accidental double processing.

  • If a response is replayed due to using the same key, the response will include the header Idempotent-Replayed: true.
  • Idempotency keys are scoped by [Key, Endpoint, HTTP Verb]; the same key on a different endpoint or method will not replay the original response.
  • Responses are cached for 24 hours. After that, the cache is cleared, so idempotency is only guaranteed within 24 hours of the initial request.

Request Body

application/json

Webhook configuration payload.

TypeScript Definitions

Use the request body type in TypeScript.

Payload for registering a webhook endpoint.

urlstring
Required

HTTPS URL that will receive webhook notifications. Must match one of your approved point-of-sale domains.

Format:
uri

List of webhook events to subscribe to. Duplicate values are rejected.

Items:
1 <= items
secretstring
Required

Shared secret used as the value of the Authorization header during webhook callback.

Length:
1 <= length <= 2048

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/public/api/v1/webhooks" \  -H "Idempotency-Key: c4f5e8d2-1234-5678-90ab-cdef12345678" \  -H "Content-Type: application/json" \  -d '{    "url": "http://example.com",    "events": [      "transaction.success.v1"    ],    "secret": "string"  }'
{  "webhook": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "url": "http://example.com",    "events": [      "subscription-billing.charge-created.v1"    ],    "pausedAt": "2019-08-24T14:15:22Z",    "pauseReason": "ERROR_RATE_TOO_HIGH",    "createdAt": "2019-08-24T14:15:22Z"  }}
{  "errorCode": "SERVER_ERROR",  "message": "An unexpected system error"}
{  "errorCode": "VALIDATION_ERROR",  "message": "Input validation errors",  "errors": {    "amount": [      "[required]: Is a required non-nullable field",      "[int]: Must be an integer",      "[min:0]: Must be greater than 0",      "[max:999999999]: Must be less than 999999999"    ]  }}
{  "errorCode": "SERVER_ERROR",  "message": "An unexpected system error"}

List Webhooks

Returns a paginated list of active webhooks configured for the authenticated merchant. Use this endpoint to audit webhook destinations, verify subscribed events, and ensure each webhook aligns with your point-of-sale domains. Webhooks are not required Webhooks are separate from the main payment flow and act as a general event notification system. You should use them only if you need to track changes to your ePay data in a system that is different from the one initiating the request. For all payment-related operations, you should use the notificationUrl provided in each request. This is the primary mechanism for receiving the outcome of a payment or operation.

Delete Webhook

Deletes a webhook configuration, stopping ePay from delivering further notifications to the URL. Webhooks are not required Webhooks are separate from the main payment flow and act as a general event notification system. You should use them only if you need to track changes to your ePay data in a system that is different from the one initiating the request. For all payment-related operations, you should use the notificationUrl provided in each request. This is the primary mechanism for receiving the outcome of a payment or operation.