Create webhook subscription

curl -X POST https://client.api.corpx.com/v1/webhooks \
     -H "X-Content-SHA256: X-Content-SHA256" \
     -H "X-Request-Signature: X-Request-Signature" \
     -H "X-Request-Timestamp: X-Request-Timestamp" \
     -H "X-Tenant-Id: X-Tenant-Id" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "url": "https://myapp.com/webhooks",
  "eventTypes": [
    "pix.in.completed",
    "qrcode.paid"
  ],
  "authType": "NONE",
  "secret": "whsec_9f8e7d6c5b4a3f2e1d0c",
  "accountId": "acc-123"
}'

{
  "subscriptionId": "8c1f6a2e-4d3b-4b9a-9f0e-1a2b3c4d5e6f",
  "tenantId": "tn_7f3a9c",
  "url": "https://example.com/webhooks/corpx",
  "active": true,
  "eventTypes": [
    "pix.in.completed"
  ],
  "authType": "HMAC",
  "hmacSecretSet": true,
  "createdAt": "2026-02-20T08:33:39Z",
  "updatedAt": "2026-02-20T08:33:39Z",
  "accountId": "2e6b725b-84a0-400d-8740-22a5ba0f23e6"
}

Creates a new webhook subscription for the current tenant. Specify the URL to receive events and optionally filter by event types.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

X-Content-SHA256stringRequired

Lowercase hex SHA-256 of the body. An empty body hashes the empty string, so the header is always present. Mismatch returns 400 body_hash_mismatch.

Request

This endpoint expects an object.

urlstringRequiredformat: "uri"

URL to receive webhook events.

eventTypeslist of stringsOptional

Event types to subscribe to. If empty, subscribes to all events.

authTypeenumOptionalDefaults to NONE

Authentication applied to webhook delivery. HMAC signs each request with secret in the X-Signature header; NONE uses the platform default signature. Any other value is rejected.

Allowed values:

secretstringOptional

Secret used for HMAC signing. Required when authType is HMAC.

accountIdstringOptional

Binds the subscription to a single account: it then receives only that account’s events. Omit for a tenant-wide subscription (every account, the historical behaviour). Not editable afterwards. A credential restricted to specific accounts MUST provide it (422 account_id_required) and may only point at accounts it reaches (403 forbidden).

Binds the subscription to a single account: it then receives only that account's events. Omit for a tenant-wide subscription (every account, the historical behaviour). Not editable afterwards. A credential restricted to specific accounts MUST provide it (`422 account_id_required`) and may only point at accounts it reaches (`403 forbidden`).

Response

Webhook subscription created.

subscriptionIdstring

Unique subscription identifier.

tenantIdstring

Tenant that owns this subscription.

urlstringformat: "uri"

URL that receives webhook events.

activeboolean

Whether the subscription is active.

eventTypeslist of stringsOptional

Event types this subscription receives.

authTypeenumOptional

Authentication applied to delivery.

hmacSecretSetbooleanOptional

Whether an HMAC key is stored. The key itself is never returned by any endpoint.

createdAtdatetimeOptional

updatedAtdatetimeOptional

accountIdstring or nullOptional

Account this subscription is bound to. null means tenant-wide: it receives every account’s events.

Errors

400

Bad Request Error

500

Internal Server Error