@celigo/api-specs 0.2.208 → 0.2.210

package/dist/tool.yml

@@ -7503,26 +7503,36 @@ components:
     PGP:
       type: object
       description: |-
-        PGP encryption settings for file-based connections (ftp, s3, and similar). When set, files are
-        PGP-encrypted before upload and/or decrypted after download. Supply at least one of `publicKey`
-        (to encrypt outbound files) or `privateKey` (to decrypt inbound files); set `passphrase` whenever
-        `privateKey` is provided.
+        PGP keys and options for the file transports — `ftp`, `s3`, the on-premise file system and the
+        cloud file-provider connections such as Box, Dropbox, Google Drive, Azure Blob Storage and
+        Celigo file storage. `publicKey` encrypts the files the connection's imports write,
+        record-generated files and transferred (blob) files alike; `privateKey` with its `passphrase`
+        decrypts the files its exports read and signs encrypted output. Supply at least one of the two.
       properties:
         publicKey:
           type: string
           description: |-
-            ASCII-armored PGP public key used to encrypt outbound files before upload.
-            Set this when the connection sends encrypted files; omit it for decrypt-only connections.
+            ASCII-armored PGP public key of the recipient, used to encrypt every file an import on this
+            connection writes with `file.encrypt: pgp`; omit it for decrypt-only connections. Returned
+            in clear on reads.
           x-celigo-ai-guidance:
             - |-
-              Public key for JWT verification. Optional — used when the API requires
-              the public key to be registered for signature verification.
+              An import on this connection cannot save `file.encrypt: pgp` without it — the save fails
+              with 422 `missing_required_field` on `file.encrypt` ("pgp publicKey is required when
+              encrypt is selected to perform file encryption."); the import form disables its Encrypt
+              files control until the connection holds a key.
         privateKey:
           type: string
           writeOnly: true
           description: |-
             ASCII-armored PGP private key used to decrypt inbound files after download (encrypted at rest;
-            returned masked as `"******"`). Set this when the connection receives encrypted files.
+            returned masked as `"******"`). Set this when the connection receives encrypted files, or
+            when its imports sign what they encrypt (`file.pgp.hashAlgorithm`).
+          x-celigo-ai-guidance:
+            - |-
+              Signing needs it: an import that sets `file.pgp.hashAlgorithm` on a connection without a
+              private key fails to save with 422 `missing_required_field` on `file.pgp.hashAlgorithm`
+              ("pgp privateKey is required when hashAlgorithm is selected to perform file signature.").
         passphrase:
           type: string
           writeOnly: true
@@ -9247,10 +9257,11 @@ components:
         retryHeader:
           type: string
           description: |
-            HTTP response header name that contains the retry delay (in seconds) when rate-limited.
-
-            Defaults to "Retry-After" which is the HTTP standard. Only change this if the API
-            uses a non-standard header name for retry-after values.
+            Response header the retry reads for its wait once a response has been recognized
+            as rate-limited — a delay in seconds or an HTTP date. It only sets the wait: a
+            response carrying the header is not treated as throttled unless a status, header
+            or body rule under `rateLimit` matches it. Change it only when the API names its
+            retry-after header differently.
           default: Retry-After
         formType:
           type: string
@@ -9980,42 +9991,60 @@ components:
         rateLimit:
           type: object
           description: |
-            Rate limiting configuration. Defines how the system detects and handles
-            API rate limit responses.
-
-            When rate limiting is detected, the system pauses requests and waits for
-            the retry-after period before resuming. The retryHeader field on the parent
-            HTTP object controls which response header contains the wait time.
+            Rules for recognizing a throttled response. When any rule is set, every response
+            through the connection is checked against the status code, the header rules and
+            the body rule, and the first match marks the request rate-limited; the retry then
+            waits for the header named by the parent `retryHeader` (`Retry-After` by default).
+            A 429 is recognized with no rules at all; a 2xx response is recognized only through
+            a matching `failHeaders` rule or a matching `failPath` + `failValues` pair, which is
+            how APIs that throttle inside a 200 body (GraphQL, Shopify among them) are handled.
           properties:
             failStatusCode:
               type: number
               description: |
-                HTTP status code that indicates the API is rate-limiting requests.
-                Defaults to 429 (Too Many Requests) which is the HTTP standard.
-                Change only if the API uses a non-standard status code for rate limits.
+                Status code that marks a response rate-limited in place of the standard 429.
+                Set it only when the API throttles with another non-success code; a 2xx value
+                does not make successful responses count as throttled on its own.
               default: 429
             failPath:
               type: string
               description: |
-                JSON path or XPath to check in response bodies for rate limit indicators.
-                Used when APIs return 200 OK but embed rate limit errors in the response body.
+                JSON path or XPath to the body field that carries the API's throttle indicator,
+                for APIs that answer 200 with the error inside the body. Point at the field
+                itself (`errors.0.extensions.code`), not at the array or object around it, and
+                pair it with `failValues`, which supplies the values that mean "throttled".
               examples:
-                - errors[0].code
+                - errors.0.extensions.code
+              x-celigo-ai-guidance:
+                - |-
+                  Saves on its own (the probe shows a `failPath` with no `failValues` is accepted),
+                  and the documented contract recognizes a 200 as throttled only when `failValues`
+                  is set as well. For Shopify GraphQL the platform's own example is
+                  `errors.0.extensions.code` with `failValues: ["THROTTLED"]`.
             failValues:
               type: array
               items:
                 type: string
               description: |
-                Values at failPath that indicate rate limiting. Requires failPath to be set.
+                Values at `failPath` that mean the request was throttled; a match on any of them
+                marks the response rate-limited.
               examples:
-                - - rate_limit_exceeded
-                  - too_many_requests
+                - - THROTTLED
+                  - MAX_COST_EXCEEDED
+              x-celigo-ai-guidance:
+                - |-
+                  Needs `failPath`: `failValues` without it fails the save with 422
+                  `dependent_field` ("The field: failValues should not be specified without the
+                  field: failPath for the Connection.").
             failHeaders:
               type: array
               description: |
-                Response-header rules for detecting rate limiting, each a header `name` with an
-                optional `value`. A rule with an empty `name` fails the save with 422
-                `invalid_header_format`.
+                Response-header rules for recognizing a throttled response, each a header `name`
+                with an optional `value`. A rule with a `value` matches when the response header
+                carries that value — the stored text is compared with the header as received; a
+                rule with no `value` matches whenever the header is present at all, so a header
+                the API sends on every response (a remaining-quota counter) would mark every
+                response throttled — give such a header a value.
               items:
                 type: object
                 required:
@@ -10026,18 +10055,32 @@ components:
                     description: Response header the rule checks.
                   value:
                     type: string
-                    description: Header value the rule checks; omit to check the header alone.
+                    description: Header value the rule compares with the response header; omit to match on the header's presence alone. Stored as sent.
               examples:
                 - - name: X-RateLimit-Remaining
                     value: '0'
+              x-celigo-ai-guidance:
+                - |-
+                  A rule without a `name` fails the save with 422 `invalid_header_format`; a rule
+                  with a name and no value saves and matches on presence. The value is stored as
+                  sent and not validated at save time.
             limit:
               type: number
               minimum: 1
+              x-celigo-ui-override: Semantics mirror the connection form, which labels the field "Wait time between HTTP requests" and requires the value in milliseconds (fieldDefinitions/resources/connection.js 'http.rateLimit.limit').
               description: |
-                Maximum number of requests per rate-limit window. When set, the connection's
-                effective concurrency level must be 1 to ensure proper rate limit enforcement.
+                Minimum spacing between consecutive requests through the connection, in
+                milliseconds, for APIs that cap request rate rather than concurrency. It only
+                applies when the connection runs one request at a time.
               examples:
                 - 1000
+              x-celigo-ai-guidance:
+                - |-
+                  Saves only when `concurrencyLevel` is 1 — and, with `autoRecoverRateLimitErrors`
+                  on, `targetConcurrencyLevel` is 1 as well; otherwise the save fails with 422
+                  `invalid_concurrency_level` ("The field "connection.http.concurrencyLevel"
+                  should be set to 1 when the field "connection.http.rateLimit.limit" is
+                  populated."). A numeric string is stored as a number.
         headers:
           type: array
           description: |
@@ -20787,6 +20830,11 @@ components:
               - Use `"csv"` for flat tabular data, spreadsheet-like records
               - Use `"xml"` for XML-based integrations, SOAP services
               - Use `"xlsx"` for Excel-compatible outputs
+            - |-
+              What writes the file's content differs by type: `csv` and `xlsx` are mapping-driven
+              (the mapped record's fields become the columns); `json` is mapping-driven too unless
+              `json.body` is set; `xml` always needs the `xml.body` template; `filedefinition` takes
+              the file definition's rules. Pick the type first, then author only that type's block.
         encoding:
           type: string
           enum:
@@ -20881,14 +20929,33 @@ components:
           x-enumDescriptions:
             pgp: Encrypt the file with PGP before it is written.
           description: |-
-            Encrypts the output file; omit it for an unencrypted file. `pgp` requires
-            `pgp.symmetricKeyAlgorithm` and a connection holding the recipient's public key
-            (`pgp.publicKey`) — without either the save fails with 422 `missing_required_field`.
-            The public-key check runs first: on a connection without one, any `encrypt` value,
-            `false` included, fails with 422 `missing_required_field` "pgp publicKey is required
-            when encrypt is selected to perform file encryption." before the value is checked.
-            Blob (file-transfer) imports follow the same rule and return `encrypt` and `pgp` even
-            without `file.type`.
+            Encrypts the file before it reaches the destination — a file generated from records
+            or, on a `blob: true` transfer, the existing file being moved; omit it for an
+            unencrypted file. `pgp` requires `pgp.symmetricKeyAlgorithm` and a connection holding
+            the recipient's public key (`pgp.publicKey`). Not observed in a run here; per the file
+            adaptor's code (IO-213945, the `blob: true` transfer path): with no `compressionFormat`,
+            a file over 200 MB fails the record before encryption with `pgp_file_size_exceeded`
+            ("The file size exceeds the maximum limit of 200 MB supported for PGP encryption." —
+            the adaptor's `errorStore.js` text); with `compressionFormat` set the adaptor skips that
+            pre-check (the compressed size is not known up front) and the encryption service
+            enforces its own 200 MB limit on the compressed file (`S3_FILE_SIZE_EXCEEDED`); a key
+            the platform cannot use fails with the PGP service's own code (`PGP_PUBLICKEY_INVALID` /
+            `PGP_PRIVATEKEY_INVALID` — "<operation> failed because the <key> is invalid."), and
+            `encryption_error` ("error in encrypting the file") only when the service returns no
+            code; the file is never written in clear and a transfer's encryption failure is not
+            retried automatically. A file generated from records meets the same encryption-service
+            limit with `S3_FILE_SIZE_EXCEEDED`.
+          x-celigo-ui-override: 'The transfer forms for FTP, S3, the on-premise file system and the cloud file providers (Box, Dropbox, Google Drive, Azure Blob Storage, Google Cloud Storage, Azure Data Lake Storage Gen2, Celigo file storage) offer the Encrypt files control in both modes (imports/subForms/fileAdvanced.js: ''pgpencrypt'' visible for inputMode records and blob, disabled until the connection holds a PGP key). The connection-side PGP section (connections/subForms/fileAdvanced.js) is mounted by ftp.js, s3.js, filesystem.js, celigoapis.ts, tp.js and the Box / Dropbox / Google Drive / Azure storage account custom HTTP forms; the Google Cloud Storage (httpFramework.js) and ADLS Gen2 (http.js) connection forms do not mount it, so on those two the key is set through the API. The AS2, VAN and NetSuite file cabinet import forms do not carry the control.'
+          x-celigo-ai-guidance:
+            - |-
+              Without `pgp.symmetricKeyAlgorithm` the save fails with 422 `missing_required_field` on
+              `file.pgp.symmetricKeyAlgorithm`; on a connection without `pgp.publicKey` it fails with
+              422 `missing_required_field` on `file.encrypt` ("pgp publicKey is required when encrypt
+              is selected to perform file encryption."), and that check runs first, for any value.
+            - |-
+              `true` and `false` are rejected with 422 `enum` — the field is the string `pgp`, never a
+              boolean. Blob transfers follow the same save rules and return `encrypt` and `pgp` on
+              reads even without `file.type`.
         csv:
           type: object
           description: CSV-specific configuration. Only used when `type` is `"csv"`.
@@ -20928,6 +20995,41 @@ components:
           type: object
           description: JSON-specific configuration. Only used when `type` is `"json"`.
           properties:
+            body:
+              type: string
+              x-celigo-agent:
+                - handlebars
+              description: |-
+                Handlebars template for the generated JSON document — the *Build JSON document*
+                editor. Rendered once per file against the records of the page, after the mapping:
+                text before the `{{#each batch_of_records}}` loop is the file's header, the loop
+                body is written once per record, text after it is the footer; under
+                `aggregation.type: all` the loop's output for every page of the run is written
+                between one header and one footer. Omit it to write the mapped records as a JSON
+                array per file.
+              x-celigo-ai-guidance:
+                - |-
+                  Leave this out unless the user needs a custom document shape: with no body the
+                  platform writes each file as a JSON array of the mapped records. A saved body
+                  overrides that — a leftover `{}` body writes literal `{}` files.
+                - |-
+                  When a body is needed, wrap the per-record part in `{{#each batch_of_records}} …
+                  {{/each}}` and address the record inside it as `record.<field>` (a grouped record
+                  as `{{#each rows}} … {{/each}}`); `{{{jsonSerialize record}}}` with
+                  `{{#unless @last}},{{/unless}}` between elements is the common form. The JSON
+                  generator recognises only that loop: a `{{#each data}}` loop is written whole per
+                  page and the pages are joined with commas (`[…],[…]`, invalid JSON under one file
+                  per run). At the root there is no `record`: `{{record.<field>}}` or a bare
+                  `{{<field>}}` outside the loop renders empty, while `batch_of_records` is in
+                  scope (`batch_of_records.0.record.<field>` is the first record when a header needs
+                  it). A body with no loop is rendered whole once per page — `{"id": {{record.id}} }`
+                  becomes `{"id":  }` per page — and under `aggregation.type: all` the pages are
+                  joined with commas (`{"id":  },{"id":  }`), which is invalid JSON even when each
+                  page's own text was valid.
+                - |-
+                  The template renders against the page whatever `http.batchSize` says, and `http.body`
+                  plays no part in the file's content. The field's editor Preview does not run the
+                  generator, so judge the body by a run.
             resourcePath:
               type: string
               description: JSONPath expression to locate records within the JSON structure.
@@ -20935,6 +21037,39 @@ components:
           type: object
           description: XML-specific configuration. Only used when `type` is `"xml"`.
           properties:
+            body:
+              type: string
+              x-celigo-agent:
+                - handlebars
+              description: |-
+                Handlebars template for the generated XML document — the *Build XML document*
+                editor. Rendered once per file against the records of the page, after the mapping:
+                text before the record loop is the file's header, the loop body is written once per
+                record, text after it is the footer; under `aggregation.type: all` the loop's
+                output for every page of the run is written between one header and one footer.
+                Must be set when `type` is `"xml"` — there is no mapping-driven XML.
+              x-celigo-ai-guidance:
+                - |-
+                  Author it as header + record loop + footer: the XML declaration and root element
+                  around `{{#each batch_of_records}} … {{/each}}`, with the record addressed inside
+                  the loop as `record.<field>` (a grouped record as `{{#each rows}} … {{/each}}`,
+                  nested elements as `{{#each record.<list>}} … {{/each}}`). The XML generator also
+                  accepts the legacy `{{#each data}} … {{/each}}`, which binds the record itself as
+                  `this` (`{{<field>}}`). At the root there is no `record`: `{{record.<field>}}` or
+                  a bare `{{<field>}}` outside the loop renders empty, while `batch_of_records` is in
+                  scope (`batch_of_records.0.record.<field>` is the first record when a header needs
+                  it). A body with no loop is rendered whole once per page — `<root>{{record.id}}</root>`
+                  becomes `<root></root>` per page — and under `aggregation.type: all` the pages are
+                  concatenated into one multi-root file (`<root></root><root></root>`); the import
+                  form does not let a one-file-per-run XML template without an each block save,
+                  while an API save writes that file.
+                - |-
+                  The template renders against the page whatever `http.batchSize` says, and on an
+                  HTTP file-provider import `http.body` plays no part in the file's content. The
+                  field's editor Preview does not run the generator, so judge the body by a run.
+                - |-
+                  Saving `type: xml` without this field fails with 422 `missing_required_field`
+                  ("required field, file.xml.body is missing.").
             resourcePath:
               type: string
               description: XPath expression to locate records within the XML structure.
@@ -21092,10 +21227,16 @@ components:
                 sha384: SHA-384 signing hash.
                 sha512: SHA-512 signing hash.
                 sha224: SHA-224 signing hash.
-              description: Hash algorithm used when signing the encrypted file; set only when the recipient requires a specific one.
+              description: Hash algorithm used when signing the encrypted file; set only when the recipient requires a signature, which also needs the connection's `pgp.privateKey` and `pgp.passphrase`.
               examples:
                 - sha256
                 - sha512
+              x-celigo-ai-guidance:
+                - |-
+                  On a connection without `pgp.privateKey` the save fails with 422
+                  `missing_required_field` on `file.pgp.hashAlgorithm` ("pgp privateKey is required
+                  when hashAlgorithm is selected to perform file signature."); leave it unset unless
+                  the connection holds the private key.
         skipRename:
           type: boolean
           description: |-
@@ -21225,6 +21366,19 @@ components:
               description: Provider-native ID of the storage root the backup relative path resolves against; set when pathMode is relativePath.
               examples:
                 - 1qU1hvFarBFMb4-twqKm1rR5o_6j9vs9g
+      if:
+        properties:
+          type:
+            const: xml
+        required:
+          - type
+      then:
+        required:
+          - xml
+        properties:
+          xml:
+            required:
+              - body
     FileSystem:
       type: object
       description: |-
@@ -27455,6 +27609,9 @@ components:
             - exported_to_netsuite
     Webhook:
       type: object
+      required:
+        - verify
+      x-celigo-ui-override: 'verify is required by the webhook listener form for every provider (exports/webhook.js: verify required:true; on a connector-backed listener the form pre-fills it from the connector definition before saving). The API enforces it only when provider is custom or absent — 422 missing_required_field on webhook.verify, "verify is required for export type webhook, provider = custom". For the named providers probed (slack, shopify, github) it stores a listener posted with key and no verify (201 each; the GET carries provider, key and formType simple) and requires a credential instead: without key (and no token) each answers 422 missing_required_field on webhook.key — "key is required for slack verification" / "key is required for shopify verification" / "key is required for github verification"; a slack listener posted with token and no key saved. Other named providers are unprobed. The requirement is kept so an authored document matches a form-saved one.'
       description: Configuration for webhook listeners that receive data through incoming HTTP requests. Required when the export's `type` is `webhook`; omit for other export types. Senders POST to the export's listener URL, `https://api.integrator.io/v1/exports/{_id}/data` (or the same path on the account's regional API host); the platform validates each request using the configured `verify` method, passes the payload to subsequent flow steps, and returns a configurable HTTP response to the caller. A request is answered 204 by default when accepted, 401 when it fails verification, and 403 `unable_to_run_flows` while every flow the export feeds is disabled; a refused request is not queued, so the sender must resend it.
       x-celigo-ai-guidance:
         - Configuration object for real-time event listeners that receive data via incoming HTTP requests.
@@ -27529,7 +27686,7 @@ components:
       properties:
         provider:
           type: string
-          description: Source application sending the webhook, used to pre-configure security settings and payload parsing for that platform. Use `custom` (the default when omitted) for unlisted providers or when you need full manual control over the security configuration. Provider-specific choices may require credentials (tokens, keys) mandated by that platform.
+          description: 'Source application sending the webhook. A named provider labels the listener and opens it in the Simple form view, where the form pre-fills that platform''s verification settings and payload parsing before saving; the API itself stores the document as sent and fills nothing in. Use `custom` (the default when omitted) for unlisted providers or when you need full manual control over the security configuration. A named provider requires a credential: `key` for the providers probed (shopify, github, slack — and slack also saves with `token` alone); the HMAC settings a provider''s form pre-fills are the form''s, not an API requirement (see the guidance below).'
           x-celigo-ai-guidance:
             - |-
               Specifies the source application sending webhook data,
@@ -27540,10 +27697,18 @@ components:
               This field determines how the webhook handles incoming requests:
 
               - OPTIONAL: Defaults to "custom" if not specified
-              - When a specific provider is selected, the system:
-                1. Pre-configures appropriate security settings for that platform
-                2. Applies platform-specific payload parsing rules
-                3. May enable additional features only relevant to that provider
+              - A named provider labels the listener, picks its form view (`formType`
+                defaults to `simple`) and makes a credential required — probed for
+                `slack`, `shopify` and `github`: without `key` (and no `token`) each
+                fails with 422 missing_required_field on `webhook.key`, "key is required
+                for slack verification" / "key is required for shopify verification" /
+                "key is required for github verification"; a `slack` listener posted
+                with `token` and no `key` saved. It does NOT make the API fill in
+                `verify` and its companions — a document sent to the API stores exactly
+                what it carries, and the listener form fills them from the connector
+                definition before saving. Send them when the stored document should
+                match a form-saved one (Slack: `verify: hmac`, `algorithm: sha256`,
+                `encoding: base64`, `header: X-Slack-Signature`).
             - |-
               ## IMPLEMENTATION GUIDANCE
 
@@ -27553,9 +27718,10 @@ components:
               ```
               "provider": "shopify"
               ```
-              - Automatically configures proper HMAC verification settings
-              - Optimizes payload parsing for Shopify's webhook format
-              - May enable additional Shopify-specific features
+              - Labels the listener as Shopify's and opens it in the Simple form view
+              - Requires `key` (422 "key is required for shopify verification"); saves
+                without `verify` and its companions, which the form would have filled in —
+                send them for a document that matches a form-saved one
 
               ### Custom configuration
 
@@ -27571,7 +27737,7 @@ components:
 
               Choose a specific provider when:
               - The source system is explicitly listed in the enum values
-              - You want to leverage pre-configured settings
+              - You want the form's pre-filled verification settings for that platform
               - The integration must follow platform-specific practices
 
               Choose "custom" when:
@@ -27618,7 +27784,7 @@ components:
             shopify: Shopify store event webhooks with HMAC-SHA256 verification.
             travis: Travis CI build event webhooks (travis-ci.com).
             travis-org: Travis CI build event webhooks (travis-ci.org).
-            slack: Slack workspace event webhooks with token verification.
+            slack: Slack workspace event webhooks. The Simple form pre-fills HMAC-SHA256 over the `X-Slack-Signature` header with the app's signing secret as `key`; the API itself accepts either `key` or `token` as the credential (probed 2026-10-29) and pre-fills nothing.
             dropbox: Dropbox file change notification webhooks.
             onfleet: Onfleet delivery management event webhooks.
             helpscout: Help Scout customer support event webhooks.
@@ -27660,13 +27826,19 @@ components:
             Which webhook export form the UI uses to edit this listener. A value sent on create or
             update wins (case-insensitive — `Simple` is stored as `simple`); a PUT that omits it
             keeps the stored value, and a new export without one gets the default for its
-            `provider`. Every webhook export GET carries it.
-          examples:
-            - webhook
+            `provider`. Every webhook export GET carries it. The view changes nothing at run time:
+            the listener URL, the verification and the flows are the same in both.
+          x-celigo-ai-guidance:
+            - |-
+              Omit it on create — the API stamps the provider's default (`simple` for a named
+              provider, `webhook` for `custom`), with or without `_httpConnectorId`, and keeps a
+              value the user set by hand. The legacy UI values `http` / `assistant` fail with 422
+              `enum`, and the field is not PATCH-whitelisted (422 "not a whitelisted property"):
+              change it through a full save.
         verify:
           type: string
           x-celigo-ui-override: Required by the webhook export form (verify is required:true). Encoded to mirror the form so builders produce connectable configurations.
-          description: 'Verification method applied to every incoming request before processing; required for all webhook exports. Each method needs companion fields: `hmac` requires `key`, `algorithm`, `encoding`, and `header` (except on connector-backed webhooks, where the connector definition supplies them); `token` requires `token`, with `tokenLocation` defaulting to `body` and selecting which location-specific field applies; `basic` requires `username` and `password`; `secret_url` requires `token`. Prefer `hmac` when the source system supports it — it is the most secure option; `secret_url` relies only on URL obscurity and suits non-sensitive data or testing.'
+          description: 'Verification method applied to every incoming request before processing; required for all webhook exports. Each method needs companion fields: `hmac` requires `key`, `algorithm`, `encoding`, and `header` (on connector-backed webhooks the form does not require them — it fills them from the connector definition before saving; the API itself copies nothing); `token` requires `token`, with `tokenLocation` defaulting to `body` and selecting which location-specific field applies; `basic` requires `username` and `password`; `secret_url` requires `token`. Prefer `hmac` when the source system supports it — it is the most secure option; `secret_url` relies only on URL obscurity and suits non-sensitive data or testing.'
           x-celigo-ai-guidance:
             - |-
               ## FIELD BEHAVIOR
@@ -28110,6 +28282,32 @@ components:
           format: objectId
           x-celigo-refModel: httpconnectors
           description: HTTP connector backing this listener when the webhook is provided by an assistant/connector (e.g. Slack); set by the platform for connector-backed listeners.
+          x-celigo-ai-guidance:
+            - |-
+              The save stores the document as sent and copies nothing from the connector: a
+              listener posted with only `provider`, `key` and (optionally) `_httpConnectorId`
+              saves with no `verify`, `algorithm`, `encoding` or `header` (probed for `slack`
+              and `shopify`) — the API requires a credential for the provider and nothing else:
+              without `key` (and no `token`) `slack`, `shopify` and `github` each fail with 422
+              missing_required_field on `webhook.key` ("key is required for slack verification" /
+              "key is required for shopify verification" / "key is required for github
+              verification"), and a `slack` listener posted with `token` and no `key` saves. The
+              listener form fills the verification fields from the connector's
+              `supportedBy.export.preConfiguredFields` on every save (for Slack `verify: hmac`,
+              `algorithm: sha256`, `encoding: base64`, `header: X-Slack-Signature`); an API
+              caller that wants the stored document to match a form-saved one sends them itself.
+        _httpConnectorApiId:
+          type: string
+          format: objectId
+          x-celigo-refModel: httpconnectorapis
+          description: API of a multi-API connector (an entry of the connector's `apis[]`) this listener is bound to — the form's API type, offered in the Simple view; omit for single-API connectors and universal webhooks.
+          examples:
+            - 673702e2f367e6469401dcf6
+          x-celigo-ai-guidance:
+            - |-
+              Stored and echoed as sent on create and GET; a value that is not an ObjectId fails
+              the save with 422 `invalid_field` ("Invalid value … for field
+              'webhook._httpConnectorApiId'. Reason: BSONError.").
         requestMediaType:
           type: string
           enum:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.208",
+  "version": "0.2.210",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [