Skip to main content
POST
/
webhook_endpoints
Create a webhook endpoint subscription
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
}
'
{
  "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": "whsec_0dd4b245a4d0e52378158d69e34c73e1ef64896ddbf14cdd76e1234abcd5678",
  "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>"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.arcuserp.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

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
​
url
string<uri>
required

HTTPS endpoint Arcus will POST events to. Must not be a private/loopback address.

​
enabled_events
string[]
required

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"
]
​
events
string[]

Deprecated. Use enabled_events instead. Accepted for back-compat; ignored when enabled_events is also present. Removed in v2.

​
description
string | null

Human-readable label for this endpoint (optional).

​
mode
enum<string>
default:live

live endpoints receive production events; test endpoints receive test-mode events only.

Available options:
live,
test
​
api_version
string | null

Pin this endpoint to a specific API version for payload serialization (optional).

​
metadata
object

Arbitrary key-value pairs (up to 50 keys). Stored and returned as-is.

​
send_test_event_on_create
boolean
default:false

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.

​
id
string<uuid>
​
object
enum<string>
Available options:
webhook_endpoint
​
entity_id
string<uuid>
​
url
string<uri>

HTTPS endpoint receiving events.

​
description
string | null
​
enabled_events
string[]

Event types this endpoint subscribes to. Wildcards supported: * (all 118 events) or <family>.* (e.g. order.*).

Example:
[
  "order.confirmed",
  "payment.succeeded",
  "fulfillment.shipped"
]
​
secret_last4
string | null

Last 4 hex chars of the signing secret (for identification only).

​
status
enum<string>

active receives events; paused skips delivery (retains subscription); disabled is permanently off.

Available options:
active,
paused,
disabled
​
mode
enum<string>

live endpoints receive production events; test endpoints receive test-mode events only.

Available options:
live,
test
​
api_version
string | null
​
success_count
integer

Total successful deliveries (HTTP 2xx).

​
failure_count
integer

Total failed deliveries (non-2xx or timeout).

​
consecutive_failure_count
integer

Consecutive failures since last success. 5+ consecutive failures auto-pauses the endpoint.

​
last_delivery_at
string<date-time> | null
​
created_at
string<date-time>
​
metadata
object

Arbitrary key-value pairs stored by the creator.

​
secret
string

One-time plaintext signing secret (format whsec_<hex>). Store immediately.

Example:

"whsec_0dd4b245a4d0e52378158d69e34c73e1ef64896ddbf14cdd76e1234abcd5678"

​
test_event
object

Present when send_test_event_on_create=true.