curl --request POST \
--url https://api.sbx.moduluslabs.io/v1/webhook_endpoints \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"url": "<string>",
"enabled_events": [],
"description": "<string>",
"metadata": {}
}
'import requests
url = "https://api.sbx.moduluslabs.io/v1/webhook_endpoints"
payload = {
"url": "<string>",
"enabled_events": [],
"description": "<string>",
"metadata": {}
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({url: '<string>', enabled_events: [], description: '<string>', metadata: {}})
};
fetch('https://api.sbx.moduluslabs.io/v1/webhook_endpoints', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sbx.moduluslabs.io/v1/webhook_endpoints",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => '<string>',
'enabled_events' => [
],
'description' => '<string>',
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sbx.moduluslabs.io/v1/webhook_endpoints"
payload := strings.NewReader("{\n \"url\": \"<string>\",\n \"enabled_events\": [],\n \"description\": \"<string>\",\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sbx.moduluslabs.io/v1/webhook_endpoints")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"<string>\",\n \"enabled_events\": [],\n \"description\": \"<string>\",\n \"metadata\": {}\n}")
.asString();using RestSharp;
var options = new RestClientOptions("https://api.sbx.moduluslabs.io/v1/webhook_endpoints");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("X-API-Key", "<api-key>");
request.AddJsonBody("{\n \"url\": \"<string>\",\n \"enabled_events\": [],\n \"description\": \"<string>\",\n \"metadata\": {}\n}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
{
"id": "ddf3d980-40b9-4aee-91b0-b95d5f29d296",
"url": "https://merchant.example/webhooks/modulus",
"description": "Production payment events",
"enabled_events": [
"payment.succeeded",
"payment.declined",
"payment.failed",
"payment.expired"
],
"status": "ENABLED",
"metadata": {},
"created_at": "2026-09-18T08:00:00.000Z",
"updated_at": "2026-09-18T08:00:00.000Z"
}{
"error": {
"code": "INVALID_DESCRIPTION",
"message": "description must be 255 characters or fewer.",
"correlation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "INVALID_DESCRIPTION",
"message": "description must be 255 characters or fewer.",
"correlation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "INVALID_DESCRIPTION",
"message": "description must be 255 characters or fewer.",
"correlation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "INVALID_DESCRIPTION",
"message": "description must be 255 characters or fewer.",
"correlation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "INVALID_DESCRIPTION",
"message": "description must be 255 characters or fewer.",
"correlation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "INVALID_DESCRIPTION",
"message": "description must be 255 characters or fewer.",
"correlation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}Create Webhook Endpoint
Register an HTTPS endpoint for Payment Webhook events
curl --request POST \
--url https://api.sbx.moduluslabs.io/v1/webhook_endpoints \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"url": "<string>",
"enabled_events": [],
"description": "<string>",
"metadata": {}
}
'import requests
url = "https://api.sbx.moduluslabs.io/v1/webhook_endpoints"
payload = {
"url": "<string>",
"enabled_events": [],
"description": "<string>",
"metadata": {}
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({url: '<string>', enabled_events: [], description: '<string>', metadata: {}})
};
fetch('https://api.sbx.moduluslabs.io/v1/webhook_endpoints', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sbx.moduluslabs.io/v1/webhook_endpoints",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => '<string>',
'enabled_events' => [
],
'description' => '<string>',
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sbx.moduluslabs.io/v1/webhook_endpoints"
payload := strings.NewReader("{\n \"url\": \"<string>\",\n \"enabled_events\": [],\n \"description\": \"<string>\",\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sbx.moduluslabs.io/v1/webhook_endpoints")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"<string>\",\n \"enabled_events\": [],\n \"description\": \"<string>\",\n \"metadata\": {}\n}")
.asString();using RestSharp;
var options = new RestClientOptions("https://api.sbx.moduluslabs.io/v1/webhook_endpoints");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("X-API-Key", "<api-key>");
request.AddJsonBody("{\n \"url\": \"<string>\",\n \"enabled_events\": [],\n \"description\": \"<string>\",\n \"metadata\": {}\n}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
{
"id": "ddf3d980-40b9-4aee-91b0-b95d5f29d296",
"url": "https://merchant.example/webhooks/modulus",
"description": "Production payment events",
"enabled_events": [
"payment.succeeded",
"payment.declined",
"payment.failed",
"payment.expired"
],
"status": "ENABLED",
"metadata": {},
"created_at": "2026-09-18T08:00:00.000Z",
"updated_at": "2026-09-18T08:00:00.000Z"
}{
"error": {
"code": "INVALID_DESCRIPTION",
"message": "description must be 255 characters or fewer.",
"correlation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "INVALID_DESCRIPTION",
"message": "description must be 255 characters or fewer.",
"correlation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "INVALID_DESCRIPTION",
"message": "description must be 255 characters or fewer.",
"correlation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "INVALID_DESCRIPTION",
"message": "description must be 255 characters or fewer.",
"correlation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "INVALID_DESCRIPTION",
"message": "description must be 255 characters or fewer.",
"correlation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "INVALID_DESCRIPTION",
"message": "description must be 255 characters or fewer.",
"correlation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}id.Authorizations
A Modulus API key with the required webhook scope.
Body
Public HTTPS callback URL.
Distinct payment event types to deliver to this endpoint. At least one is required.
1Payment event type delivered to a subscribed endpoint.
payment.succeeded, payment.declined, payment.failed, payment.expired Optional merchant-defined label for the endpoint. Maximum 255 characters.
255Optional endpoint metadata. At most 50 keys, 40 characters per key, and 500 characters per string value. null is stored as an empty object.
Response
Endpoint created. The signing secret is not included; retrieve it through the signing-secret operation.
Unique webhook endpoint identifier.
Public HTTPS callback URL that receives subscribed events.
Payment event types currently delivered to this endpoint.
Payment event type delivered to a subscribed endpoint.
payment.succeeded, payment.declined, payment.failed, payment.expired Delivery state of the endpoint.
ENABLED, DISABLED Merchant-owned endpoint metadata. This is endpoint configuration and is not payment-event metadata.
UTC RFC 3339 timestamp when the endpoint was created.
UTC RFC 3339 timestamp when the endpoint was last updated.
Merchant-defined endpoint label, or null when none was supplied.
Was this page helpful?