Compeller Webhooks API

Register HTTPS endpoints for signed push notifications on compel terminal events.

GitHub OpenAPI

Operations 7

POST /api/v1/webhooks Register a webhook endpoint #
GET /api/v1/webhooks List registered webhooks for the caller's account #
GET /api/v1/webhooks/{id} Fetch a single webhook by id (secret is redacted) #
PATCH /api/v1/webhooks/{id} Update mutable fields on a webhook (url, events, active) #
DELETE /api/v1/webhooks/{id} Delete a webhook #
POST /api/v1/webhooks/{id}/rotate-secret Mint a new HMAC signing secret (returned exactly once) #
POST /api/v1/webhooks/{id}/test Synchronously deliver a synthetic `webhook.test` event to this endpoint #

Work with this as data

Every API 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 apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • 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 API
curl "https://apis.io/api/v1/apis/compeller-ai:compeller-ai-webhooks-api"
All apis
curl "https://apis.io/api/v1/apis?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.

OpenAPI Specification

compeller-ai-webhooks-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Compeller Ai Webhooks API
  version: 1.0.0
  description: 'Operations tagged Webhooks across 2 of this provider''s published API definitions: compeller-ai-openapi.yaml, compeller-ai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://compeller.ai
  description: Production
- url: https://dev.compeller.ai
  description: Development
security:
- bearerToken: []
- apiTokenHeader: []
tags:
- name: Webhooks
  description: Register HTTPS endpoints for signed push notifications on compel terminal events.
paths:
  /api/v1/webhooks:
    post:
      tags:
      - Webhooks
      operationId: createWebhook
      summary: Register a webhook endpoint
      description: 'Registers an HTTPS endpoint to receive `compel.ready`, `compel.completed`, and

        `compel.failed` events for the caller''s account. The response includes a `secret` that is only

        ever returned on this call - store it immediately; there is no rotate-secret

        endpoint in this cut.


        **URL safety.** Destinations that point at internal infrastructure are rejected

        with `422 Invalid url`:

        - loopback (`127.0.0.0/8`, `::1`) and `localhost`

        - RFC1918 private ranges (`10/8`, `172.16/12`, `192.168/16`)

        - link-local (`169.254/16` - includes `169.254.169.254` cloud metadata,

        `fe80::/10`)

        - IPv6 unique-local `fc00::/7`

        - IPv4 CGNAT `100.64/10`

        - the unspecified address (`0.0.0.0`, `::`) and multicast

        - hostnames ending in `.local`, `.internal`, `.localhost`


        The same checks re-run at delivery time against resolved DNS, so a hostname

        that resolves to a blocked IP after registration is silently skipped (logged,

        not retried).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreateRequest'
      responses:
        '201':
          description: Webhook created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCreateResponse'
        '400':
          $ref: '#/components/responses/Problem'
        '401':
          $ref: '#/components/responses/Problem'
        '422':
          $ref: '#/components/responses/Problem'
    get:
      tags:
      - Webhooks
      operationId: listWebhooks
      summary: List registered webhooks for the caller's account
      responses:
        '200':
          description: Webhook list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'
        '401':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://compeller.ai
      description: Production
    - url: https://dev.compeller.ai
      description: Development
  /api/v1/webhooks/{id}:
    get:
      tags:
      - Webhooks
      operationId: getWebhook
      summary: Fetch a single webhook by id (secret is redacted)
      parameters:
      - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Webhook envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEnvelope'
        '401':
          $ref: '#/components/responses/Problem'
        '404':
          $ref: '#/components/responses/Problem'
    patch:
      tags:
      - Webhooks
      operationId: updateWebhook
      summary: Update mutable fields on a webhook (url, events, active)
      description: 'Partial update. Any of `url`, `events`, `active` may be provided; at

        least one is required. URL safety checks from registration apply -

        destinations pointing at internal infrastructure are rejected with

        `422 Invalid url`. The response redacts the secret; use

        `POST /api/v1/webhooks/{id}/rotate-secret` to mint a new one.'
      parameters:
      - $ref: '#/components/parameters/PathId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookUpdateRequest'
      responses:
        '200':
          description: Updated webhook (secret redacted).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEnvelope'
        '400':
          $ref: '#/components/responses/Problem'
        '401':
          $ref: '#/components/responses/Problem'
        '404':
          $ref: '#/components/responses/Problem'
        '422':
          $ref: '#/components/responses/Problem'
    delete:
      tags:
      - Webhooks
      operationId: deleteWebhook
      summary: Delete a webhook
      parameters:
      - $ref: '#/components/parameters/PathId'
      responses:
        '204':
          description: Webhook deleted.
        '401':
          $ref: '#/components/responses/Problem'
        '404':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://compeller.ai
      description: Production
    - url: https://dev.compeller.ai
      description: Development
  /api/v1/webhooks/{id}/rotate-secret:
    post:
      tags:
      - Webhooks
      operationId: rotateWebhookSecret
      summary: Mint a new HMAC signing secret (returned exactly once)
      description: 'Generates a fresh 64-char hex secret, stores it on the endpoint, and

        returns it in the response. The previous secret is invalidated

        immediately - integrators must update their receiver before the next

        compel terminal event fires. There is no separate "confirm" step.'
      parameters:
      - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Webhook with the newly minted secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCreateResponse'
        '401':
          $ref: '#/components/responses/Problem'
        '404':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://compeller.ai
      description: Production
    - url: https://dev.compeller.ai
      description: Development
  /api/v1/webhooks/{id}/test:
    post:
      tags:
      - Webhooks
      operationId: testWebhook
      summary: Synchronously deliver a synthetic `webhook.test` event to this endpoint
      description: 'Sends one HMAC-signed test POST to the endpoint''s URL and returns the result

        synchronously. Uses the same signature header (`X-Compeller-Signature`) and

        URL safety checks as real deliveries, so a URL that now resolves to a

        blocked address returns `delivered: false` with an `error` field instead of

        being sent.


        Does **not** filter by the endpoint''s `events` subscription - the test is

        always delivered regardless of what the endpoint is subscribed to.


        A non-2xx response from the endpoint is surfaced as `delivered: false` but

        the HTTP call to this API still returns `200 OK` - the test result itself

        is the payload. Only auth and not-found errors produce RFC 7807 4xx.'
      parameters:
      - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Test delivery result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookTestResult'
        '401':
          $ref: '#/components/responses/Problem'
        '404':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://compeller.ai
      description: Production
    - url: https://dev.compeller.ai
      description: Development
components:
  schemas:
    WebhookEnvelope:
      type: object
      required:
      - webhook
      properties:
        webhook:
          $ref: '#/components/schemas/Webhook'
    WebhookTestResult:
      type: object
      description: 'Outcome of a synchronous `POST /api/v1/webhooks/{id}/test` call. `delivered`

        is `true` only on a 2xx response; blocked URLs, DNS failures, connect

        errors, timeouts, and non-2xx all surface as `delivered: false` with a

        human-readable `error` string.

        '
      required:
      - webhook_id
      - event_id
      - event_type
      - delivered
      - latency_ms
      properties:
        webhook_id:
          type: integer
          format: int64
        event_id:
          type: string
          example: evt_f3d2e7c...
        event_type:
          type: string
          enum:
          - webhook.test
        delivered:
          type: boolean
        response_status:
          type:
          - integer
          - 'null'
          description: HTTP status returned by the endpoint, if one was received.
        response_body_preview:
          type:
          - string
          - 'null'
          description: First 200 chars of the endpoint's response body, if any.
        latency_ms:
          type: integer
          description: Wall time from safety check to response parsed, in milliseconds.
        error:
          type:
          - string
          - 'null'
          description: 'Populated when `delivered` is false. Examples:

            `"url host ''169.254.169.254'' resolves to a reserved or internal address"`,

            `"ConnectException: Connection refused"`, `"endpoint returned HTTP 500"`.

            '
    Webhook:
      type: object
      required:
      - id
      - url
      - events
      - active
      - created_at
      properties:
        id:
          type: integer
          format: int64
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
          example:
          - '*'
        active:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
    WebhookCreateResponse:
      type: object
      required:
      - webhook
      properties:
        webhook:
          $ref: '#/components/schemas/WebhookWithSecret'
    WebhookCreateRequest:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
          description: HTTPS target URL. Must start with `https://`.
          example: https://integrator.example.com/webhooks/compeller
        events:
          description: 'Subscribed event types. Accepts an array or comma-separated string.

            Use `*` (the default) to subscribe to every type this account publishes.

            Unknown values are dropped silently; if the filtered list is empty the

            subscription falls back to `*` so no caller gets a silent no-op.

            '
          oneOf:
          - type: array
            items:
              type: string
              enum:
              - '*'
              - compel.ready
              - compel.completed
              - compel.failed
          - type: string
            example: compel.ready,compel.completed
    Problem:
      type: object
      description: RFC 7807 problem detail.
      required:
      - type
      - title
      - status
      properties:
        type:
          type: string
          example: about:blank
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
    WebhookWithSecret:
      allOf:
      - $ref: '#/components/schemas/Webhook'
      - type: object
        required:
        - secret
        properties:
          secret:
            type: string
            description: 'HMAC-SHA256 signing key for this endpoint. Returned exactly once on the

              create response - store it immediately. There is no rotate-secret

              endpoint in this cut.

              '
            example: 4b3c2f1e0a9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b
    WebhookUpdateRequest:
      type: object
      description: 'Partial update payload. At least one of `url`, `events`, `active` must

        be provided. Fields not present are left unchanged.

        '
      minProperties: 1
      properties:
        url:
          type: string
          format: uri
          description: Replacement HTTPS URL. Runs the same safety checks as registration.
        events:
          description: 'Replacement event subscription. Accepts an array or comma-separated

            string (same shape as `WebhookCreateRequest`). Unknown values are

            dropped; an all-dropped list falls back to `*`.

            '
          oneOf:
          - type: array
            items:
              type: string
              enum:
              - '*'
              - compel.ready
              - compel.completed
              - compel.failed
          - type: string
        active:
          type: boolean
          description: Toggle delivery on/off without losing the registration or secret.
    WebhookList:
      type: object
      required:
      - webhooks
      properties:
        webhooks:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'
  responses:
    Problem:
      description: RFC 7807 problem detail.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  parameters:
    PathId:
      name: id
      in: path
      required: true
      schema:
        type: integer
        format: int64
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: 'Compeller API token sent as `Authorization: Bearer <token>`.'
    apiTokenHeader:
      type: apiKey
      in: header
      name: X-API-Token
      description: 'Compeller API token sent as `X-API-Token: <token>` (equivalent to bearer).'
x-refined-from:
- compeller-ai-openapi.yaml
- compeller-ai-openapi.yml