Skip to main content
POST
/
v1
/
webhooks
/
endpoints
Create Webhook Endpoint
curl --request POST \
  --url https://your-endpoint.moduluslabs.io/v1/webhooks/endpoints \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "url": "https://api.yourcompany.com/webhooks/payments",
  "events": [
    "payment.completed",
    "payment.failed",
    "payment.cancelled",
    "payment.timeout"
  ],
  "description": "Production payment notifications",
  "metadata": {
    "environment": "production"
  }
}
'
{
  "endpointId": "wh_01HQ3K4M5N6P7R8S9T0UVWXYZ",
  "url": "https://api.yourcompany.com/webhooks/payments",
  "events": [
    "payment.completed",
    "payment.failed",
    "payment.cancelled",
    "payment.timeout"
  ],
  "description": "Production payment notifications",
  "secret": "whsec_abc123xyz789...",
  "status": "active",
  "metadata": {
    "environment": "production"
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}
This endpoint requires HMAC-SHA256 authentication. See Authentication for signature computation details.

​
Endpoint Validation

When you create a webhook endpoint, the system sends a validation ping to verify that the URL is publicly accessible. The endpoint must:
  1. Use HTTPS protocol
  2. Be publicly reachable from the internet
  3. Respond with a 2xx status code to the ping request
If the validation ping fails, the endpoint will not be created. Ensure your URL is accessible before attempting to register it.

​
Endpoint Limits

Each group can configure up to 16 webhook endpoints. Attempting to create more will return an ENDPOINT_LIMIT_REACHED error.

​
Signing Secret

The response includes a secret field that is used to verify webhook signatures. This secret is only returned once during endpoint creation.
Store the webhook signing secret securely. You’ll need it to verify incoming webhook payloads. See Receiving Webhooks for signature verification details.

​
Event Types

Subscribe to one or more event types:
EventDescription
payment.completedPayment succeeded on the terminal
payment.failedPayment was declined or encountered an error
payment.cancelledUser cancelled the payment
payment.timeoutTerminal didn’t respond within 90 seconds

Authorizations

​
x-api-key
string
header
required

HMAC-SHA256 authentication. Requires three headers: x-api-key (your API key), x-timestamp (ISO 8601 timestamp), and x-signature (Base64-encoded HMAC-SHA256 signature). See Authentication documentation for signature computation.

Body

application/json

Webhook endpoint configuration

​
url
string<uri>
required

The HTTPS URL where webhook payloads will be delivered. Must be publicly accessible.

​
events
enum<string>[]
required

Array of event types to subscribe to.

Available options:
payment.completed,
payment.failed,
payment.cancelled,
payment.timeout
​
description
string

Human-readable description for this endpoint.

​
metadata
object

Custom key-value pairs to associate with this endpoint.

Response

Webhook endpoint created successfully

​
endpointId
string
required

Unique identifier for the webhook endpoint.

​
url
string<uri>
required

The HTTPS URL where webhook payloads are delivered.

​
events
enum<string>[]
required

Event types this endpoint is subscribed to.

Available options:
payment.completed,
payment.failed,
payment.cancelled,
payment.timeout
​
secret
string
required

Webhook signing secret. Only returned on endpoint creation. Store securely for signature verification.

​
status
enum<string>
required

Endpoint status.

Available options:
active,
disabled
​
createdAt
string<date-time>
required

ISO 8601 timestamp of when the endpoint was created.

​
updatedAt
string<date-time>
required

ISO 8601 timestamp of the last update.

​
description
string

Human-readable description for this endpoint.

​
metadata
object

Custom key-value pairs associated with this endpoint.