Scope: developers:webhooks.write https://api.alladdin.com/api/v2/webhooks

Creates a new webhook subscription for the account.

Request body

object url string<uri> required

Callback URL

events[] string[] required

Events to subscribe to

version string | null optional

API version (defaults to v1)

Enum: v1 `` description string optional

Human-readable description

Request

import requests

url = "https://api.alladdin.com/api/v2/webhooks"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json",
}

payload = {
    "url": "https://example.com/webhook",
    "events": [
        "invoice.create",
        "invoice.update"
    ],
    "version": "v1",
    "description": "My webhook"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

Responses

Response

{
  "id": "507f1f77bcf86cd799439011",
  "url": "https://example.com/webhook",
  "events": [
    "invoice.create",
    "invoice.update"
  ],
  "version": "v1",
  "description": "My webhook",
  "enabled": true,
  "created_at": "2026-01-15T10:30:00+00:00",
  "updated_at": "2026-01-15T10:30:00+00:00",
  "secret": "whsec_abc123",
  "disable": {
    "at": "2026-01-15T10:30:00+00:00",
    "reason": "Endpoint returning 5xx errors",
    "by": {
      "id": "507f1f77bcf86cd799439011",
      "type": "user"
    }
  }
}

Success responses

201 Webhook created application/json object id string url string<uri> events[] string[] version string description string enabled boolean created_at string<date-time> updated_at string<date-time> | null secret string disable object | null at string<date-time> reason string by object | null

Error responses

400 Bad request application/json 401 Invalid or missing API key application/json 403 Insufficient permissions application/json 409 An event subscription already exists for this account 422 The URL is not publicly accessible 429 Rate limit exceeded application/json

Next →Disable a webhook →