Create a webhook endpoint
curl --request POST \
--url https://api.arcuserp.com/v1/webhook_endpoints \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "<string>",
"enabled_events": [
"order.confirmed",
"payment.succeeded",
"fulfillment.shipped"
],
"events": [
"<string>"
],
"description": "<string>",
"mode": "live",
"api_version": "<string>",
"metadata": {},
"send_test_event_on_create": false
}
'import requests
url = "https://api.arcuserp.com/v1/webhook_endpoints"
payload = {
"url": "<string>",
"enabled_events": ["order.confirmed", "payment.succeeded", "fulfillment.shipped"],
"events": ["<string>"],
"description": "<string>",
"mode": "live",
"api_version": "<string>",
"metadata": {},
"send_test_event_on_create": False
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: '<string>',
enabled_events: ['order.confirmed', 'payment.succeeded', 'fulfillment.shipped'],
events: ['<string>'],
description: '<string>',
mode: 'live',
api_version: '<string>',
metadata: {},
send_test_event_on_create: false
})
};
fetch('https://api.arcuserp.com/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.arcuserp.com/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' => [
'order.confirmed',
'payment.succeeded',
'fulfillment.shipped'
],
'events' => [
'<string>'
],
'description' => '<string>',
'mode' => 'live',
'api_version' => '<string>',
'metadata' => [
],
'send_test_event_on_create' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.arcuserp.com/v1/webhook_endpoints"
payload := strings.NewReader("{\n \"url\": \"<string>\",\n \"enabled_events\": [\n \"order.confirmed\",\n \"payment.succeeded\",\n \"fulfillment.shipped\"\n ],\n \"events\": [\n \"<string>\"\n ],\n \"description\": \"<string>\",\n \"mode\": \"live\",\n \"api_version\": \"<string>\",\n \"metadata\": {},\n \"send_test_event_on_create\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.arcuserp.com/v1/webhook_endpoints")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"<string>\",\n \"enabled_events\": [\n \"order.confirmed\",\n \"payment.succeeded\",\n \"fulfillment.shipped\"\n ],\n \"events\": [\n \"<string>\"\n ],\n \"description\": \"<string>\",\n \"mode\": \"live\",\n \"api_version\": \"<string>\",\n \"metadata\": {},\n \"send_test_event_on_create\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.arcuserp.com/v1/webhook_endpoints")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"<string>\",\n \"enabled_events\": [\n \"order.confirmed\",\n \"payment.succeeded\",\n \"fulfillment.shipped\"\n ],\n \"events\": [\n \"<string>\"\n ],\n \"description\": \"<string>\",\n \"mode\": \"live\",\n \"api_version\": \"<string>\",\n \"metadata\": {},\n \"send_test_event_on_create\": false\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"object": "webhook_endpoint",
"entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "<string>",
"description": "<string>",
"enabled_events": [
"order.confirmed",
"payment.succeeded",
"fulfillment.shipped"
],
"secret_last4": "<string>",
"status": "active",
"mode": "live",
"api_version": "<string>",
"success_count": 123,
"failure_count": 123,
"consecutive_failure_count": 123,
"last_delivery_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"metadata": {},
"secret": "[REDACTED, see CREDENTIALS.env]",
"test_event": {
"event_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"queued_delivery_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "queued_pending_infra_011",
"infra_011_notice": "<string>"
}
}{
"error": "not_found",
"code": "not_found",
"type": "not_found",
"hint": "The requested order does not exist or does not belong to this entity.",
"param": "expand[0]",
"required": "accounts:read",
"request_id": "req_abc123"
}{
"error": "not_found",
"code": "not_found",
"type": "not_found",
"hint": "The requested order does not exist or does not belong to this entity.",
"param": "expand[0]",
"required": "accounts:read",
"request_id": "req_abc123"
}{
"error": "duplicate_url",
"existing_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": "not_found",
"code": "not_found",
"type": "not_found",
"hint": "The requested order does not exist or does not belong to this entity.",
"param": "expand[0]",
"required": "accounts:read",
"request_id": "req_abc123"
}Webhooks
Create a webhook endpoint
Registers an outbound webhook endpoint that receives a signed JSON payload whenever a subscribed event fires, using enabled_events to choose which events (the older events field is accepted but deprecated). The response includes a one-time plaintext signing secret used to verify each delivery’s Arcus-Signature header, store it immediately since it is never shown again; requires webhooks:manage scope.
POST
/
webhook_endpoints
Create a webhook endpoint
curl --request POST \
--url https://api.arcuserp.com/v1/webhook_endpoints \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "<string>",
"enabled_events": [
"order.confirmed",
"payment.succeeded",
"fulfillment.shipped"
],
"events": [
"<string>"
],
"description": "<string>",
"mode": "live",
"api_version": "<string>",
"metadata": {},
"send_test_event_on_create": false
}
'import requests
url = "https://api.arcuserp.com/v1/webhook_endpoints"
payload = {
"url": "<string>",
"enabled_events": ["order.confirmed", "payment.succeeded", "fulfillment.shipped"],
"events": ["<string>"],
"description": "<string>",
"mode": "live",
"api_version": "<string>",
"metadata": {},
"send_test_event_on_create": False
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: '<string>',
enabled_events: ['order.confirmed', 'payment.succeeded', 'fulfillment.shipped'],
events: ['<string>'],
description: '<string>',
mode: 'live',
api_version: '<string>',
metadata: {},
send_test_event_on_create: false
})
};
fetch('https://api.arcuserp.com/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.arcuserp.com/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' => [
'order.confirmed',
'payment.succeeded',
'fulfillment.shipped'
],
'events' => [
'<string>'
],
'description' => '<string>',
'mode' => 'live',
'api_version' => '<string>',
'metadata' => [
],
'send_test_event_on_create' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.arcuserp.com/v1/webhook_endpoints"
payload := strings.NewReader("{\n \"url\": \"<string>\",\n \"enabled_events\": [\n \"order.confirmed\",\n \"payment.succeeded\",\n \"fulfillment.shipped\"\n ],\n \"events\": [\n \"<string>\"\n ],\n \"description\": \"<string>\",\n \"mode\": \"live\",\n \"api_version\": \"<string>\",\n \"metadata\": {},\n \"send_test_event_on_create\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.arcuserp.com/v1/webhook_endpoints")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"<string>\",\n \"enabled_events\": [\n \"order.confirmed\",\n \"payment.succeeded\",\n \"fulfillment.shipped\"\n ],\n \"events\": [\n \"<string>\"\n ],\n \"description\": \"<string>\",\n \"mode\": \"live\",\n \"api_version\": \"<string>\",\n \"metadata\": {},\n \"send_test_event_on_create\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.arcuserp.com/v1/webhook_endpoints")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"<string>\",\n \"enabled_events\": [\n \"order.confirmed\",\n \"payment.succeeded\",\n \"fulfillment.shipped\"\n ],\n \"events\": [\n \"<string>\"\n ],\n \"description\": \"<string>\",\n \"mode\": \"live\",\n \"api_version\": \"<string>\",\n \"metadata\": {},\n \"send_test_event_on_create\": false\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"object": "webhook_endpoint",
"entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "<string>",
"description": "<string>",
"enabled_events": [
"order.confirmed",
"payment.succeeded",
"fulfillment.shipped"
],
"secret_last4": "<string>",
"status": "active",
"mode": "live",
"api_version": "<string>",
"success_count": 123,
"failure_count": 123,
"consecutive_failure_count": 123,
"last_delivery_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"metadata": {},
"secret": "[REDACTED, see CREDENTIALS.env]",
"test_event": {
"event_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"queued_delivery_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "queued_pending_infra_011",
"infra_011_notice": "<string>"
}
}{
"error": "not_found",
"code": "not_found",
"type": "not_found",
"hint": "The requested order does not exist or does not belong to this entity.",
"param": "expand[0]",
"required": "accounts:read",
"request_id": "req_abc123"
}{
"error": "not_found",
"code": "not_found",
"type": "not_found",
"hint": "The requested order does not exist or does not belong to this entity.",
"param": "expand[0]",
"required": "accounts:read",
"request_id": "req_abc123"
}{
"error": "duplicate_url",
"existing_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": "not_found",
"code": "not_found",
"type": "not_found",
"hint": "The requested order does not exist or does not belong to this entity.",
"param": "expand[0]",
"required": "accounts:read",
"request_id": "req_abc123"
}Authorizations
API key issued per entity via Settings > Developers > API Keys.
Each key carries scopes (e.g. orders:read, products:write).
Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity
via Settings > Developers > API Keys.
Body
application/json
HTTPS endpoint Arcus will POST events to. Must not be a private/loopback address.
Event types this endpoint subscribes to. Use * for all 118 events,
<family>.* for a whole family (e.g. order.*), or individual event
names (e.g. order.confirmed). Must be non-empty.
Example:
[
"order.confirmed",
"payment.succeeded",
"fulfillment.shipped"
]
Deprecated. Use enabled_events instead. Accepted for back-compat;
ignored when enabled_events is also present. Removed in v2.
Human-readable label for this endpoint (optional).
live endpoints receive production events; test endpoints receive test-mode events only.
Available options:
live, test Pin this endpoint to a specific API version for payload serialization (optional).
Arbitrary key-value pairs (up to 50 keys). Stored and returned as-is.
When true, queues an immediate webhook.test delivery to this endpoint
on creation. The response includes test_event.event_id and
test_event.queued_delivery_id. Delivery fires once INFRA-011
(webhook deliverer Lambda) is provisioned.
Response
Webhook endpoint created. The secret field is present ONCE in this response only.
An outbound webhook endpoint subscription. Arcus delivers signed JSON payloads
to the url whenever a subscribed event fires.
Field names: the subscription list is enabled_events (Stripe convention).
The deprecated alias events is accepted in request bodies for back-compat
and will be removed in v2.
Available options:
webhook_endpoint HTTPS endpoint receiving events.
Event types this endpoint subscribes to. Wildcards supported: * (all 118 events)
or <family>.* (e.g. order.*).
Example:
[
"order.confirmed",
"payment.succeeded",
"fulfillment.shipped"
]
Last 4 hex chars of the signing secret (for identification only).
active receives events; paused skips delivery (retains subscription); disabled is permanently off.
Available options:
active, paused, disabled live endpoints receive production events; test endpoints receive test-mode events only.
Available options:
live, test Total successful deliveries (HTTP 2xx).
Total failed deliveries (non-2xx or timeout).
Consecutive failures since last success. 5+ consecutive failures auto-pauses the endpoint.
Arbitrary key-value pairs stored by the creator.
One-time plaintext signing secret (format whsec_<hex>). Store immediately.
Example:
"[REDACTED, see CREDENTIALS.env]"
Present when send_test_event_on_create=true.
Show child attributes
Show child attributes
Was this page helpful?