Create webhook configuration

curl -X POST https://api.useroot.com/api/webhooks \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "url": "https://example.com/webhook",
  "event_types": [
    "payout.settled",
    "payout.failed",
    "payin.settled"
  ],
  "description": "Payment notifications webhook"
}'

{
  "data": {
    "created_at": "2024-03-20T12:00:00Z",
    "updated_at": "2024-03-20T12:00:00Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "url": "https://example.com/webhook",
    "description": "Payment notifications webhook",
    "is_active": true,
    "event_types": [
      "payin.failed",
      "payin.settled",
      "payout.debited",
      "payout.failed",
      "payout.settled",
      "subaccount.credit_received"
    ],
    "secret_key": "verySecureRandomKeyThatIsLongEnough"
  }
}

Creates a new webhook configuration for the entity. The generated secret key is returned only in this initial response and should be stored securely.

Authentication

x-api-keystring

RootPay API key sent in the x-api-key header. Keys are environment-scoped: live_* for production, test_* for sandbox.

Request

This endpoint expects an object.

urlstringRequiredformat: "uri"1-2083 characters

event_typeslist of enumsRequired

Non-empty allowlist of subscribed webhook event types. Persisted as NOT NULL on webhook_configs (see migration backfill).

descriptionstring or nullOptional

Response

Webhook configuration created successfully

dataobject

Response model for webhook creation that includes the secret key.

warningstring or null