beel-es · Schema

WebhookSubscriptionWithSecret

InvoicingSpainFintechSoftware-as-a-Service

Properties

Name Type Description
id string
url string
events array
active boolean 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 d
account_relationship object Which accounts this subscription receives events from. Same field name and values as the `account_relationship` carried by every event envelope.
deactivated_by object 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 — reactivati
deactivated_at stringnull When the subscription was turned off. Null while it is active.
last_error stringnull Last error seen in the current run of failed deliveries — what to fix. Cleared by the first successful delivery, together with the failure count.
last_error_cause object Stable code for `last_error`. Cleared alongside it by the first successful delivery.
consecutive_failures integer 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
last_used_at stringnull Last delivery that succeeded. Null if none ever has.
created_at string
secret string HMAC-SHA256 signing secret. **Only returned on creation and secret rotation.** Store it securely — it cannot be retrieved again.
test_delivery object Outcome of a one-off signed test delivery sent to your URL as part of creating the subscription, so you learn whether your endpoint answers without a second call. It is **best effort and never blocks
View JSON Schema on GitHub

JSON Schema

beel-es-webhook-subscription-with-secret-schema.json Raw ↑
{
  "$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"
        }
      }
    }
  }
}

Work with this as data

Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for schemas

4 MCP tools reach this
  • find_json_schemasBrowse and filter every JSON Schema in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/beel-es-webhook-subscription-with-secret"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.