{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/beel-es/json-schema/beel-es-webhook-subscription-with-secret-schema.json",
  "title": "WebhookSubscriptionWithSecret",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/beel-es-accountwebhooks-api-openapi.yml#/components/schemas/WebhookSubscriptionWithSecret",
  "allOf": [
    {
      "$ref": "#/$defs/WebhookSubscription"
    },
    {
      "type": "object",
      "properties": {
        "secret": {
          "type": "string",
          "description": "HMAC-SHA256 signing secret. **Only returned on creation and secret rotation.**\nStore it securely — it cannot be retrieved again.\n"
        },
        "test_delivery": {
          "allOf": [
            {
              "$ref": "#/$defs/WebhookTestResult"
            }
          ],
          "description": "Outcome of a one-off signed test delivery sent to your URL as part of creating the\nsubscription, so you learn whether your endpoint answers without a second call.\n\nIt is **best effort and never blocks the subscription**: the subscription in `data`\nexists and is active regardless of what this says, and the field is `null` when the\ntest could not be run at all. A failure here means your endpoint is not ready yet —\ntypically because you registered before deploying it — not that anything went wrong\nwith the registration. Only present on creation, never on secret rotation.\n"
        }
      }
    }
  ],
  "$defs": {
    "WebhookAccountRelationship": {
      "type": "string",
      "enum": [
        "own",
        "managed",
        "all"
      ],
      "description": "Which accounts a subscription receives events from — the same vocabulary as the\n`account_relationship` field in every delivered event envelope. One term to ask for\nevents, the same term to route them on arrival.\n\n* `own` (default) — only your own account.\n* `managed` — only accounts you manage (accounts you provisioned). Whether you actually\n  receive them also depends on the management relationship granting data visibility; a\n  billing-only relationship does not.\n* `all` — both.\n\nA delivered event is always `own` or `managed` (never `all`): its\n`account_relationship`, alongside `account_id` and `account_external_ref`, tells you\nwhich account it belongs to.\n"
    },
    "WebhookDeactivationCause": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "owner",
        "beel"
      ],
      "description": "Who turned a subscription off, alongside `active: false`.\n\n* `owner` — you did, through the API or the dashboard. Turn it back on whenever you want.\n* `beel` — we did, because the endpoint stopped accepting anything at all for days.\n  Reactivating requires the endpoint to pass a test delivery first (`POST\n  /v1/webhooks/{webhook_id}/test`), so you unblock yourself without opening a ticket.\n"
    },
    "WebhookFailureCause": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "dns",
        "connection",
        "tls",
        "timeout",
        "http_client_error",
        "http_server_error",
        "invalid_url",
        "forbidden_target",
        "unknown"
      ],
      "description": "Why a delivery to your endpoint did not succeed. The `error` field is free text meant for\na human reading a log; this field is the machine-readable counterpart, so a change in\nwording never changes your branching.\n\n* `dns` — the endpoint's domain does not resolve.\n* `connection` — the connection could not be opened (refused, host unreachable).\n* `tls` — the endpoint's TLS certificate is not valid or not trusted.\n* `timeout` — the endpoint accepted the connection but did not answer in time.\n* `http_client_error` — the endpoint answered 4xx.\n* `http_server_error` — the endpoint answered 5xx.\n* `invalid_url` — the subscription URL is malformed and has no host to deliver to.\n* `forbidden_target` — the URL points to a non-public network address, which we never\n  deliver to.\n* `unknown` — the failure could not be classified.\n\nNew values may be added over time. Treat any value you do not recognise as `unknown`.\n"
    },
    "WebhookSubscription": {
      "type": "object",
      "required": [
        "id",
        "url",
        "events",
        "active",
        "created_at"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "events": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "active": {
          "type": "boolean",
          "description": "Whether the subscription receives events. Turning it off, or BeeL. pausing it, drops the deliveries still waiting for an automatic retry: they are not sent when it is turned back on, and stay in the delivery log for a manual retry.\n"
        },
        "account_relationship": {
          "allOf": [
            {
              "$ref": "#/$defs/WebhookAccountRelationship"
            }
          ],
          "description": "Which accounts this subscription receives events from. Same field name and values as the `account_relationship` carried by every event envelope.\n"
        },
        "deactivated_by": {
          "allOf": [
            {
              "$ref": "#/$defs/WebhookDeactivationCause"
            }
          ],
          "description": "Who turned this subscription off. Absent while it is active. `beel` means we paused it because the endpoint went 25 consecutive deliveries without a single success over more than 48 hours — reactivating it requires a successful test delivery first.\n"
        },
        "deactivated_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When the subscription was turned off. Null while it is active."
        },
        "last_error": {
          "type": [
            "string",
            "null"
          ],
          "description": "Last error seen in the current run of failed deliveries — what to fix. Cleared by the first successful delivery, together with the failure count.\n"
        },
        "last_error_cause": {
          "allOf": [
            {
              "$ref": "#/$defs/WebhookFailureCause"
            }
          ],
          "description": "Stable code for `last_error`. Cleared alongside it by the first successful delivery.\n"
        },
        "consecutive_failures": {
          "type": "integer",
          "description": "Deliveries in a row that never got through. A delivery that exhausted its attempts counts as one. Any successful delivery resets it to zero, so a healthy endpoint with occasional blips stays near zero.\n"
        },
        "last_used_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Last delivery that succeeded. Null if none ever has."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "WebhookTestResult": {
      "type": "object",
      "properties": {
        "delivery_success": {
          "type": "boolean",
          "description": "Whether your endpoint responded with HTTP 2xx."
        },
        "http_status": {
          "type": [
            "integer",
            "null"
          ],
          "description": "HTTP status code returned by your endpoint. Null if the connection failed."
        },
        "duration_ms": {
          "type": "integer",
          "description": "Round-trip time in milliseconds."
        },
        "error": {
          "type": [
            "string",
            "null"
          ],
          "description": "Error message if the delivery failed (timeout, DNS, etc.)."
        },
        "failure_cause": {
          "allOf": [
            {
              "$ref": "#/$defs/WebhookFailureCause"
            }
          ],
          "description": "Why the delivery failed, as a stable code. Absent when `delivery_success` is true. Branch on this, never on the wording of `error`.\n"
        }
      }
    }
  }
}