Skip to Content
Apex Settlement
Webhooks

Register a webhook endpoint

Required permissioncustomer:webhooks:manage
POST
/v1/webhooks

Registers an HTTPS URL to receive the Customer's events of the types named in events (see the webhooks of this reference for each payload). The answer carries the endpoint's signing secret, whsec_…, in secret: it is shown here only, so store it to verify Apex-Signature on every delivery. The URL must be https and resolve only to public addresses. A Customer holds at most 10 endpoints, disabled ones included. A Platform's endpoints also receive its End Customers' events, marked with end_customer_id.

Requires the customer:webhooks:manage permission. Not available for an End Customer: Apex-End-Customer is refused.

Authorization

ApiKey
headerAuthorizationBearer <API key>

A Customer API key, created by a Customer admin in the Customer panel and shown once: Authorization: Bearer ak_live_… in production, ak_test_… elsewhere. A key holds a subset of its creator's permissions and may be limited to named IP addresses and an expiry date. Keys never manage people, other keys or approval rules, and never approve a Payout.

Request Body

Where to send and which events.

application/json
  1. body
events*array<>

events are the event types the endpoint receives, at most three.

Items1 <= items <= 3
url*string

url receives the deliveries: https, resolving only to public addresses.

Lengthlength <= 2048

Response Body

Created

application/json
  1. response
endpoint*
secret*string

secret signs every delivery to this endpoint; it is shown in this answer only.

Example Request
curl -X POST 'http://localhost:3480/v1/webhooks' \  -H 'Content-Type: application/json' \  -d '{  "events": [    "payout.updated",    "deposit.received"  ],  "url": "https://hooks.example.com/apex"}'
Example Response
{  "endpoint": {    "created_at": "2026-11-01T12:00:00Z",    "disabled_reason": "no successful delivery for 24 hours",    "events": [      "payout.updated",      "deposit.received"    ],    "failing_since": "2019-08-24T14:15:22Z",    "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",    "last_success_at": "2026-11-12T09:31:06Z",    "status": "active",    "updated_at": "2026-11-01T12:00:00Z",    "url": "https://hooks.example.com/apex"  },  "secret": "whsec_9fJx2Lq7Rk4mTz8vNc3bWs6yHd1gPa5e"}