Apiable

Apiable Webhooks API

# How Webhooks Work Webhooks are a way for services to communicate with each other in real time. When an event occurs, the Webhook sends an HTTP POST request to the URL that you've configured. The Webhook itself is unaware of any specific authorization mechanisms like the Apiable Lambda authorizer, and the Webhook URL can be any endpoint capable of receiving HTTP POST requests. Optionally, you can include custom headers in the request. These headers will be appended automatically by the Webhook to the HTTP POST request, adding any additional information required for the endpoint. ## Testing a Webhook before posting You can test a Webhook by sending a POST request to the Webhook URL manually. Here’s an example curl command that simulates the Webhook sending a POST request: ```bash curl -X POST https:/apiable.example.io/webhook \ -H "Content-Type: application/json" \ -H "api-key: MY-API-KEY" \ -H "Custom-Header-1: value1" \ -H "Custom-Header-2: value2" \ -d '{ "id": "67040bcb1eb964694d999a68", "events": [ "SUBSCRIPTION_CREATED" ], "whsec": "whsec_CoX***pc=" }' ``` ## Example Webhook Configuration In the following example, a Webhook is configured to send an HTTP POST request to a URL upon the occurrence of a `SUBSCRIPTION_CREATED` event. The parameters "whsec" and "headers" are optional. ```json { "id": "67040bcb1eb964694d999a68", "events": [ "SUBSCRIPTION_CREATED" ], "url": "https:/apiable.example.io/webhook", "headers": { "api-key": "MY-API-KEY", "Custom-Header-1": "value1", "Custom-Header-2": "value2" } } ```

GitHub OpenAPI

Operations 7

GET /api/webhooks/{id} Retrieve a webhook by ID #
PUT /api/webhooks/{id} Update webhook #
DELETE /api/webhooks/{id} Unregister a webhook #
GET /api/webhooks Retrieve Registered Webhooks #
POST /api/webhooks Register a webhook #
GET /api/webhooks/{id}/test Test a webhook by ID #
GET /api/webhooks/{id}/history Retrieve the history of webhook results for the past 24 hours #

Documentation

📖
APIReference
https://www.apiable.io/docs/api-reference/
📖
Documentation
https://www.apiable.io/docs/automation/
📖
Authentication
https://raw.githubusercontent.com/api-evangelist/apiable/refs/heads/main/authentication/apiable-authentication.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/apiable/refs/heads/main/openapi/apiable-webhooks-api-openapi.yml

Other Resources

🔗
OAuthScopes
https://raw.githubusercontent.com/api-evangelist/apiable/refs/heads/main/scopes/apiable-scopes.yml
🔗
Webhooks
https://raw.githubusercontent.com/api-evangelist/apiable/refs/heads/main/asyncapi/apiable-webhooks.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/apiable/refs/heads/main/errors/apiable-problem-types.yml
🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/apiable/refs/heads/main/conventions/apiable-conventions.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/apiable/refs/heads/main/data-model/apiable-data-model.yml

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/apiable-webhooks-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

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.

GitHub Google LinkedIn

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

OpenAPI Specification

apiable-webhooks-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Apiable Platform Webhooks API
  description: '## Introduction


    The Apiable Platform API is a RESTful API that allows you to manage your portal, teams, users, and subscriptions.'
  contact:
    name: Apiable Team
    url: https://apiable.io
    email: support@apiable.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: v2
servers:
- url: https://developer.apiable.io
tags:
- name: Webhooks
  description: '# How Webhooks Work


    Webhooks are a way for services to communicate with each other in real time.'
paths:
  /api/webhooks/{id}:
    get:
      tags:
      - Webhooks
      summary: Retrieve a webhook by ID
      description: Retrieve a specific webhook by its ID. This will return the webhook configuration including the events it is subscribed to, the URL, and the secret key.
      operationId: getWebhookById
      parameters:
      - name: id
        in: path
        description: The id of the webhook to retrieve.
        required: true
        style: simple
        explode: false
        schema:
          type: string
        example: 67040bcb1eb964694d999a68
      - name: X-API-Version
        in: header
        description: API version to use.
        required: false
        style: simple
        explode: false
        schema:
          type: string
          enum:
          - '2024-09-25'
      responses:
        '200':
          description: 'OK: Successfully retrieved the webhook.'
          content:
            application/json:
              schema:
                description: The webhook configuration
                properties:
                  id:
                    type: string
                  events:
                    type: array
                    description: The events the webhook is listening to
                    items:
                      type: string
                      description: The events the webhook is listening to
                      enum:
                      - SUBSCRIPTION_CREATED
                      - SUBSCRIPTION_CANCELLED
                      - SUBSCRIPTION_AUTH_CHANGED
                      - SUBSCRIPTION_CHANGED
                      - INVOICE_ATTENTION_REQUIRED
                  url:
                    type: string
                    description: The url of the webhook
                  whsec:
                    type: string
                    description: The secret of the webhook
                  authorization:
                    type: string
                    description: The authorization header of the webhook
                  headers:
                    type: object
                    additionalProperties:
                      type: string
                      description: The headers of the webhook
                    description: The headers of the webhook
              examples:
                WebhookConf Example:
                  description: Example of a webhook configuration.
                  value:
                    id: 66f6b0f0ea99a34963977e55
                    created: '2024-09-27T16:19:44.013'
                    updated: '2024-09-27T16:19:44.013'
                    name: Webhook Example
                    url: https://example.com/webhook
                    authType: BASIC_AUTH
                    authUsername: user
                    authPassword: password
                    events:
                    - SUBSCRIPTION_CREATED
                    - SUBSCRIPTION_CANCELLED
                    whsec: whsec_1234567890abcdef
                    active: true
                    version: 1
        '401':
          description: 'Unauthorized for operation: getWebhookById'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
                  status:
                    type: string
                    example: '401'
        '404':
          description: 'Not Found: The requested webhook does not exist.'
          content:
            application/json:
              schema:
                type: string
              examples:
                NotFound:
                  description: Error message when the webhook with the given ID is not found.
                  value: Webhook not found
      security:
      - oauth-cc:
        - apiable/cicd
        - apiable/platform
    put:
      tags:
      - Webhooks
      summary: Update webhook
      description: 'Update a webhook subscription by providing the URL to send the webhook to, the events to subscribe to.The webhook secret key (whsec) is optional. If not provided, a random key will be generated.

        The possible event types `SUBSCRIPTION_CREATED` and `SUBSCRIPTION_CANCELLED` are sent when a subscription is created or cancelled, respectively.'
      operationId: updateWebhook
      parameters:
      - name: id
        in: path
        description: The id of the webhook to be updated.
        required: true
        style: simple
        explode: false
        schema:
          type: string
        example: 67040bcb1eb964694d999a68
      - name: X-API-Version
        in: header
        description: API version to use.
        required: false
        style: simple
        explode: false
        schema:
          type: string
          enum:
          - '2024-09-25'
      requestBody:
        description: The expected request body for updating a webhook.
        content:
          application/json:
            schema:
              description: Webhook Configuration update request
              properties:
                events:
                  type: array
                  description: The events to subscribe to
                  items:
                    type: string
                    description: The events to subscribe to
                    enum:
                    - SUBSCRIPTION_CREATED
                    - SUBSCRIPTION_CANCELLED
                    - SUBSCRIPTION_AUTH_CHANGED
                    - SUBSCRIPTION_CHANGED
                    - INVOICE_ATTENTION_REQUIRED
                url:
                  type: string
                  description: The URL to send the webhook to
                whsec:
                  type: string
                  description: The webhook secret key
                authorization:
                  type: string
                  description: The authorization header
                headers:
                  type: object
                  additionalProperties:
                    type: string
                    description: The headers to send with the webhook
                  description: The headers to send with the webhook
            examples:
              WebhookConfUpdate:
                description: WebhookConfUpdate
                value: "\n{\n  \"url\": \"https://example.com/webhook\",\n  \"events\": [\n    \"SUBSCRIPTION_CREATED\",\n    \"SUBSCRIPTION_CANCELLED\"\n  ],\n  \"whsec\": \"whsec_1234567890abcdef\",\n}\n"
        required: true
      responses:
        '200':
          description: 'OK: Successfully updated the webhook.'
          content:
            application/json:
              schema:
                description: The webhook configuration
                properties:
                  id:
                    type: string
                  events:
                    type: array
                    description: The events the webhook is listening to
                    items:
                      type: string
                      description: The events the webhook is listening to
                      enum:
                      - SUBSCRIPTION_CREATED
                      - SUBSCRIPTION_CANCELLED
                      - SUBSCRIPTION_AUTH_CHANGED
                      - SUBSCRIPTION_CHANGED
                      - INVOICE_ATTENTION_REQUIRED
                  url:
                    type: string
                    description: The url of the webhook
                  whsec:
                    type: string
                    description: The secret of the webhook
                  authorization:
                    type: string
                    description: The authorization header of the webhook
                  headers:
                    type: object
                    additionalProperties:
                      type: string
                      description: The headers of the webhook
                    description: The headers of the webhook
              examples:
                WebhookConf Example:
                  description: Example of an updated webhook configuration.
                  value:
                    id: 66f6b0f0ea99a34963977e55
                    created: '2024-09-27T16:19:44.013'
                    updated: '2024-09-27T16:19:44.013'
                    name: Webhook Example
                    url: https://example.com/webhook
                    authType: BASIC_AUTH
                    authUsername: user
                    authPassword: password
                    events:
                    - SUBSCRIPTION_CREATED
                    - SUBSCRIPTION_CANCELLED
                    whsec: whsec_1234567890abcdef
                    active: true
                    version: 1
        '401':
          description: 'Unauthorized for operation: updateWebhook'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
                  status:
                    type: string
                    example: '401'
        '404':
          description: 'Not Found: The webhook to be updated does not exist.'
          content:
            application/json:
              schema:
                type: string
              examples:
                NotFound:
                  description: Error message when the webhook with the given ID is not found.
                  value: Webhook not found
      security:
      - oauth-cc:
        - apiable/cicd
        - apiable/platform
    delete:
      tags:
      - Webhooks
      summary: Unregister a webhook
      description: Unsubscribe from a webhook, record of the webhook will be deleted and deleted webhook will no longer receive events. Restoring a deleted webhook is not possible, instead you can create a new webhook with the same configuration.
      operationId: unregisterWebhook
      parameters:
      - name: id
        in: path
        description: The id of the webhook to be unregistered.
        required: true
        style: simple
        explode: false
        schema:
          type: string
        example: 67040bcb1eb964694d999a68
      - name: X-API-Version
        in: header
        description: API version to use.
        required: false
        style: simple
        explode: false
        schema:
          type: string
          enum:
          - '2024-09-25'
      responses:
        '204':
          description: 'No Content: Successfully unregistered the webhook.'
          content:
            application/json:
              schema:
                type: string
              examples:
                Success:
                  description: Confirmation message when the webhook is successfully unregistered.
                  value: Webhook unregistered successfully
        '401':
          description: 'Unauthorized for operation: unregisterWebhook'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
                  status:
                    type: string
                    example: '401'
        '404':
          description: 'Not Found: The webhook to be unregistered doesn''t exit.'
          content:
            application/json:
              schema:
                type: string
              examples:
                NotFound:
                  description: Error message when the webhook with the given ID is not found.
                  value: Webhook not found
      security:
      - oauth-cc:
        - apiable/cicd
        - apiable/platform
  /api/webhooks:
    get:
      tags:
      - Webhooks
      summary: Retrieve Registered Webhooks
      description: Retrieve all registered webhooks for the platform. The response will include all webhooks that are currently registered.
      operationId: findAllWebhooks
      parameters:
      - name: X-API-Version
        in: header
        description: API version to use.
        required: false
        style: simple
        explode: false
        schema:
          type: string
          enum:
          - '2024-09-25'
      responses:
        '200':
          description: 'OK: Successfully retrieved the list of registered webhooks.'
          content:
            application/json:
              schema:
                type: array
                items:
                  description: The webhook configuration
                  properties:
                    id:
                      type: string
                    events:
                      type: array
                      description: The events the webhook is listening to
                      items:
                        type: string
                        description: The events the webhook is listening to
                        enum:
                        - SUBSCRIPTION_CREATED
                        - SUBSCRIPTION_CANCELLED
                        - SUBSCRIPTION_AUTH_CHANGED
                        - SUBSCRIPTION_CHANGED
                        - INVOICE_ATTENTION_REQUIRED
                    url:
                      type: string
                      description: The url of the webhook
                    whsec:
                      type: string
                      description: The secret of the webhook
                    authorization:
                      type: string
                      description: The authorization header of the webhook
                    headers:
                      type: object
                      additionalProperties:
                        type: string
                        description: The headers of the webhook
                      description: The headers of the webhook
              examples:
                Example list of webhooks:
                  description: List of all registered webhooks on the platform.
                  value:
                  - id: 66f6b0f0ea99a34963977e55
                    created: '2024-09-27T16:19:44.013'
                    updated: '2024-09-27T16:19:44.013'
                    name: Webhook Example
                    url: https://example.com/webhook
                    authType: BASIC_AUTH
                    authUsername: user
                    authPassword: password
                    events:
                    - SUBSCRIPTION_CREATED
                    - SUBSCRIPTION_CANCELLED
                    whsec: whsec_1234567890abcdef
                    active: true
                    version: 1
        '401':
          description: 'Unauthorized for operation: findAllWebhooks'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
                  status:
                    type: string
                    example: '401'
      security:
      - oauth-cc:
        - apiable/cicd
        - apiable/platform
    post:
      tags:
      - Webhooks
      summary: Register a webhook
      description: 'Subscribe to a webhook event by providing the URL to send the webhook to, the events to subscribe to.The webhook secret key (whsec) is optional. If not provided, a random key will be generated.

        The possible event types `SUBSCRIPTION_CREATED` and `SUBSCRIPTION_CANCELLED` are sent when a subscription is created or cancelled, respectively.'
      operationId: registerWebhook
      parameters:
      - name: X-API-Version
        in: header
        description: API version to use.
        required: false
        style: simple
        explode: false
        schema:
          type: string
          enum:
          - '2024-09-25'
      requestBody:
        description: The expected request body for registering a webhook.
        content:
          application/json:
            schema:
              description: Webhook Configuration create request
              properties:
                events:
                  type: array
                  description: The events to subscribe to
                  items:
                    type: string
                    description: The events to subscribe to
                    enum:
                    - SUBSCRIPTION_CREATED
                    - SUBSCRIPTION_CANCELLED
                    - SUBSCRIPTION_AUTH_CHANGED
                    - SUBSCRIPTION_CHANGED
                    - INVOICE_ATTENTION_REQUIRED
                url:
                  type: string
                  description: The URL to send the webhook to
                whsec:
                  type: string
                  description: The webhook secret key
                authorization:
                  type: string
                  description: The authorization header
                headers:
                  type: object
                  additionalProperties:
                    type: string
                    description: The headers to send with the webhook
                  description: The headers to send with the webhook
            examples:
              WebhookConf:
                description: Example of a webhook configuration to be registered.
                value: "\n                {\n                    \"events\": [\"SUBSCRIPTION_CREATED\",\"SUBSCRIPTION_CANCELLED\"],\n                    \"url\": \"https://example.com/webhook\",\n                    \"whsec\": \"base64 encoded, prefixed with `whsec_` (Random. Between 24 bytes (192 bits) and 64 bytes (512 bits))\",\n                    \"authorization\": \"key/token - something we pass to a Authorization header e.g. 'Authorization: _bn6hgjds'\",\n                }\n            "
        required: true
      responses:
        '201':
          description: 'Created: Successfully registered the webhook.'
          content:
            application/json:
              schema:
                description: The webhook configuration
                properties:
                  id:
                    type: string
                  events:
                    type: array
                    description: The events the webhook is listening to
                    items:
                      type: string
                      description: The events the webhook is listening to
                      enum:
                      - SUBSCRIPTION_CREATED
                      - SUBSCRIPTION_CANCELLED
                      - SUBSCRIPTION_AUTH_CHANGED
                      - SUBSCRIPTION_CHANGED
                      - INVOICE_ATTENTION_REQUIRED
                  url:
                    type: string
                    description: The url of the webhook
                  whsec:
                    type: string
                    description: The secret of the webhook
                  authorization:
                    type: string
                    description: The authorization header of the webhook
                  headers:
                    type: object
                    additionalProperties:
                      type: string
                      description: The headers of the webhook
                    description: The headers of the webhook
              examples:
                WebhookConf Example:
                  description: Example of a registered webhook configuration.
                  value:
                    id: 66f6b0f0ea99a34963977e55
                    created: '2024-09-27T16:19:44.013'
                    updated: '2024-09-27T16:19:44.013'
                    name: Webhook Example
                    url: https://example.com/webhook
                    authType: BASIC_AUTH
                    authUsername: user
                    authPassword: password
                    events:
                    - SUBSCRIPTION_CREATED
                    - SUBSCRIPTION_CANCELLED
                    whsec: whsec_1234567890abcdef
                    active: true
                    version: 1
        '401':
          description: 'Unauthorized for operation: registerWebhook'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
                  status:
                    type: string
                    example: '401'
      security:
      - oauth-cc:
        - apiable/cicd
        - apiable/platform
  /api/webhooks/{id}/test:
    get:
      tags:
      - Webhooks
      summary: Test a webhook by ID
      description: Send a test event to a specific webhook by its ID. This will simulate the webhook sending a POST request to the URL configured for the webhook.The test event will be sent using the same schema as actual events, but with a different event type (TEST_EVENT).
      operationId: testWebhookById
      parameters:
      - name: id
        in: path
        description: The id of the webhook to be tested.
        required: true
        style: simple
        explode: false
        schema:
          type: string
        example: 67040bcb1eb964694d999a68
      - name: X-API-Version
        in: header
        description: API version to use.
        required: false
        style: simple
        explode: false
        schema:
          type: string
          enum:
          - '2024-09-25'
      responses:
        '200':
          description: 'OK: Successfully sent the test event to the webhook.'
          content:
            application/json:
              schema:
                type: string
              examples:
                Success:
                  description: Confirmation message when the test event is successfully sent to the webhook.
                  value: 'Test event sent to: https: with response.status: OK '
        '401':
          description: 'Unauthorized for operation: testWebhookById'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
                  status:
                    type: string
                    example: '401'
        '404':
          description: 'Not Found: The webhook to be tested does not exist.'
          content:
            application/json:
              schema:
                type: string
              examples:
                NotFound:
                  description: Error message when the webhook with the given ID is not found.
                  value: Webhook not found
      security:
      - oauth-cc:
        - apiable/cicd
        - apiable/platform
  /api/webhooks/{id}/history:
    get:
      tags:
      - Webhooks
      summary: Retrieve the history of webhook results for the past 24 hours
      description: Retrieve the history of webhook results for the past 24 hours. This includes all webhook events that were sent.
      operationId: getWebhookHistory
      parameters:
      - name: id
        in: path
        description: The id of the webhook to retrieve the history for.
        required: true
        style: simple
        explode: false
        schema:
          type: string
        example: 67040bcb1eb964694d999a68
      - name: X-API-Version
        in: header
        description: API version to use.
        required: false
        style: simple
        explode: false
        schema:
          type: string
          enum:
          - '2024-09-25'
      responses:
        '200':
          description: 'OK: Successfully retrieved the webhook history.'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              examples:
                Webhook History Example:
                  description: List of webhook history entries for the specified webhook.
                  value:
                  - Webhook event with id 67993d1b70045616067c6629 sent successfully, with status 200 OK
        '401':
          description: 'Unauthorized for operation: getWebhookHistory'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
                  status:
                    type: string
                    example: '401'
        '404':
          description: 'Not Found: The webhook does not exist.'
          content:
            application/json:
              schema:
                type: string
              examples:
                NotFound:
                  description: Error message when the webhook with the given ID is not found.
                  value: Webhook not found
      security:
      - oauth-cc:
        - apiable/cicd
        - apiable/platform
components:
  securitySchemes:
    oauth-cc:
      type: oauth2
      description: 'OAuth 2.0: Client Credentials'
      flows:
        clientCredentials:
          tokenUrl: https://developer.apiable.io/api/oauth2/token
          scopes: {}
      x-receive-token-in: request-body
      x-client-id: ''
      x-client-secret: ''