Celigo integrator.io Webhook Listeners

asyncapi: 2.6.0
info:
  title: Celigo integrator.io Webhook Listeners
  version: '1.0.0'
  description: |-
    AsyncAPI description of Celigo integrator.io's inbound webhook surface.
    integrator.io exposes "webhook listeners" that receive HTTP POST or PUT
    requests from third-party source applications. Each listener has a public
    URL that integrator.io generates automatically when the listener is
    created; the URL is shared with the source application so its webhook
    deliveries trigger a real-time integration flow inside integrator.io.

    Direction: inbound to Celigo. integrator.io is the webhook SUBSCRIBER and
    the customer's third-party application is the webhook PUBLISHER. This
    spec models the contract that integrator.io presents to those external
    publishers, not the customer-hosted endpoints used for outbound delivery.

    Source documentation:
      - Webhooks section:        https://docs.celigo.com/hc/en-us/sections/360009906491-Webhooks
      - Trigger real-time flows: https://docs.celigo.com/hc/en-us/sections/360009906491-Trigger-real-time-flows-with-webhook-events
      - Create webhook listeners: https://docs.celigo.com/hc/en-us/articles/360015827372-Create-webhook-listeners
      - Invoke integrator.io externally: https://docs.celigo.com/hc/en-us/articles/14737771807643-How-to-invoke-integrator-io-externally
      - HubSpot webhook listener: https://docs.celigo.com/hc/en-us/articles/6336823381531-Set-up-a-webhook-listener-for-HubSpot
      - Shopify webhook listener: https://docs.celigo.com/hc/en-us/articles/14983026623771-Set-up-a-Shopify-webhook-listener
      - HMAC encoding FAQ:        https://docs.celigo.com/hc/en-us/community/posts/360077335811

    Success response defaults (per Celigo documentation):
      - HTTP 204 No Content for all successful webhook requests.
      - JSON is the default success media type (XML and Plaintext are
        configurable alternatives).
      - The response body is empty by default.
      - Alternative successful HTTP status codes can be configured per
        listener.

    Rate limiting:
      The integrator.io platform applies a leaky-bucket rate limit with a
      capacity of 1,000 tokens and a refill rate of 300 tokens per second
      (documented at the platform level; webhook listeners share this limit).
  contact:
    name: Celigo Support
    url: https://docs.celigo.com/
  license:
    name: Celigo Terms of Service
    url: https://celigo.com/terms-of-service/

defaultContentType: application/json

servers:
  listener:
    url: '{listenerUrl}'
    protocol: https
    description: |-
      Public HTTPS URL of an integrator.io webhook listener. The hostname
      and path are generated by integrator.io when the listener resource is
      created and are not publicly documented as a fixed pattern, so the
      full URL is exposed here as a server variable. Operators copy this
      URL out of the integrator.io UI and paste it into the source
      application's webhook configuration.
    variables:
      listenerUrl:
        default: https://integrator.io/webhook-listener/REPLACE_WITH_GENERATED_PATH
        description: |-
          The full HTTPS URL of the deployed webhook listener as generated
          by integrator.io.
    security:
      - basicAuth: []
      - tokenAuth: []
      - hmacAuth: []
      - noAuth: []

channels:
  /:
    description: |-
      A single integrator.io webhook listener endpoint. The same URL accepts
      any payload the configured source application sends; integrator.io
      passes the request body and headers into the bound real-time flow.

      Provider-specific listener templates documented by Celigo include
      Shopify, HubSpot, and Slack, along with a generic "Webhook" application
      type for any other source that can deliver HTTP POST or PUT messages.
      The verification scheme is selected per listener (Basic, Token, HMAC,
      or none).
    bindings:
      http:
        type: request
        method: POST
        bindingVersion: 0.3.0
    publish:
      operationId: receiveWebhookEvent
      summary: Source application delivers a webhook event to integrator.io.
      description: |-
        The source application performs an HTTP POST (or PUT, where the
        source supports it) to the listener URL. integrator.io validates
        the request against the listener's configured verification scheme,
        responds with HTTP 204 (or the configured success status), and then
        triggers the bound flow with the request body and headers as the
        source record.
      bindings:
        http:
          bindingVersion: 0.3.0
      message:
        oneOf:
          - $ref: '#/components/messages/GenericWebhookEvent'
          - $ref: '#/components/messages/ShopifyWebhookEvent'
          - $ref: '#/components/messages/HubSpotWebhookEvent'
          - $ref: '#/components/messages/SlackWebhookEvent'

components:
  messages:
    GenericWebhookEvent:
      name: GenericWebhookEvent
      title: Generic webhook event
      summary: Any HTTP POST/PUT body delivered to a generic webhook listener.
      contentType: application/json
      description: |-
        For listeners created with the generic "Webhook" application type,
        integrator.io does not constrain the JSON schema of the request
        body. The body is forwarded to the bound flow as-is. The schema
        below is intentionally permissive.
      payload:
        type: object
        additionalProperties: true
    ShopifyWebhookEvent:
      name: ShopifyWebhookEvent
      title: Shopify webhook event
      summary: Real-time event delivered by Shopify to a Shopify-typed listener.
      contentType: application/json
      description: |-
        For listeners created with the Shopify application type, the body
        is the standard Shopify webhook payload (for example an Order,
        Product, or Customer resource). Celigo's documentation does not
        republish Shopify's schemas, so the payload is modelled as an open
        object; the canonical schemas live in the Shopify Admin webhook
        documentation.
      headers:
        type: object
        properties:
          X-Shopify-Topic:
            type: string
            description: Shopify event topic (for example `orders/create`).
          X-Shopify-Hmac-Sha256:
            type: string
            description: Base64-encoded HMAC-SHA256 of the raw request body.
          X-Shopify-Shop-Domain:
            type: string
            description: Source Shopify shop domain.
      payload:
        type: object
        additionalProperties: true
    HubSpotWebhookEvent:
      name: HubSpotWebhookEvent
      title: HubSpot webhook event
      summary: Event batch delivered by HubSpot to a HubSpot-typed listener.
      contentType: application/json
      description: |-
        For listeners created with the HubSpot application type, HubSpot
        posts an array of event objects. Celigo's documentation does not
        republish HubSpot's schemas, so the payload is modelled as an open
        array of objects; the canonical schemas live in HubSpot's webhook
        API documentation.
      payload:
        type: array
        items:
          type: object
          additionalProperties: true
    SlackWebhookEvent:
      name: SlackWebhookEvent
      title: Slack webhook event
      summary: Event delivered by Slack to a Slack-typed listener.
      contentType: application/json
      description: |-
        For listeners created with the Slack application type, Celigo's
        documentation calls out the `X-Slack-Signature` header used for
        HMAC verification. The body itself is whatever Slack posts (for
        example an Events API envelope) and is not republished by Celigo.
      headers:
        type: object
        properties:
          X-Slack-Signature:
            type: string
            description: HMAC signature header used by Slack webhook verification.
          X-Slack-Request-Timestamp:
            type: string
            description: Timestamp of the originating Slack request.
      payload:
        type: object
        additionalProperties: true

  securitySchemes:
    basicAuth:
      type: userPassword
      description: |-
        HTTP Basic Authentication. Documented by Celigo as relying on
        transport-level encryption; the source application sends a
        username and password configured on the listener.
    tokenAuth:
      type: httpApiKey
      name: Authorization
      in: header
      description: |-
        Token-based verification. The source application presents a token
        configured on (or generated by) the listener. The token may be
        delivered as an HTTP header or as a query parameter on the
        generated URL; this scheme models the header form.
    hmacAuth:
      type: apiKey
      in: user
      description: |-
        HMAC verification. The listener is configured with a shared secret
        and an algorithm (Celigo documents SHA-256, SHA-384, and SHA-512
        as supported choices); the source application signs the raw
        request body with the secret and delivers the signature in a
        configurable HTTP header (for example `X-Slack-Signature` for
        Slack, `X-Shopify-Hmac-Sha256` for Shopify, `X-Hub-Signature` for
        GitHub-style sources). Some providers prefix the algorithm
        identifier in the header value (`sha1=`, `sha256=`); Celigo's
        Advanced Field Editor strips that prefix before validation.
    noAuth:
      type: apiKey
      in: query
      description: |-
        No verification configured. integrator.io still requires the
        caller to know the unique generated listener URL, which acts as
        the only secret. Modelled as a query-string apiKey because the
        URL itself carries the secret path.