Extole Webhooks API

openapi: 3.0.1
info:
  description: 'Consumer-to-Extole integration endpoints: consumer event submission, zone rendering, profile management, and SDK-backing operations for browser and native app environments.'
  title: Integration API - Consumer to Extole Audiences Webhooks API
  version: '1.0'
servers:
- description: Production
  url: https://{brand}.extole.io
  variables:
    brand:
      default: yourcompany
      description: Your Extole client subdomain (e.g. 'mycompany' for mycompany.extole.io)
security:
- HEADER: []
- QUERY: []
- COOKIE: []
tags:
- name: Webhooks
paths:
  /v6/webhooks:
    get:
      description: Returns all webhooks for the client. Filter by `enabled` or `type` to narrow the result set. Use `GET /v6/webhooks/built` for the fully evaluated runtime form. Webhooks are outbound HTTP callbacks Extole fires when specific platform events occur.
      operationId: listWebhooks
      parameters:
      - in: query
        name: enabled
        schema:
          nullable: true
          type: boolean
      - in: query
        name: type
        schema:
          enum:
          - CLIENT
          - GENERIC
          - PARTNER
          - REWARD
          nullable: true
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/WebhookResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                reward_supplier_webhook_filter_is_missing:
                  $ref: '#/components/examples/reward_supplier_webhook_filter_is_missing'
                reward_supplier_webhook_filter_not_found:
                  $ref: '#/components/examples/reward_supplier_webhook_filter_not_found'
                unknown_webhook_type:
                  $ref: '#/components/examples/unknown_webhook_type'
                webhook_build_failed:
                  $ref: '#/components/examples/webhook_build_failed'
                webhook_client_key_not_found:
                  $ref: '#/components/examples/webhook_client_key_not_found'
                webhook_invalid_default_method:
                  $ref: '#/components/examples/webhook_invalid_default_method'
                webhook_invalid_description:
                  $ref: '#/components/examples/webhook_invalid_description'
                webhook_invalid_name:
                  $ref: '#/components/examples/webhook_invalid_name'
                webhook_invalid_tag:
                  $ref: '#/components/examples/webhook_invalid_tag'
                webhook_local_or_internal_url:
                  $ref: '#/components/examples/webhook_local_or_internal_url'
                webhook_malformed_url:
                  $ref: '#/components/examples/webhook_malformed_url'
                webhook_missing_name:
                  $ref: '#/components/examples/webhook_missing_name'
                webhook_missing_url:
                  $ref: '#/components/examples/webhook_missing_url'
                webhook_name_duplicate:
                  $ref: '#/components/examples/webhook_name_duplicate'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
                reward_supplier_not_found:
                  $ref: '#/components/examples/reward_supplier_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: List webhooks
      tags:
      - Webhooks
      x-extole-bundle: management
      x-extole-visibility: visible
    post:
      description: Creates a new webhook definition and returns the persisted record with its server-assigned id. The webhook fires immediately for matching events once created; set `enabled=false` in the request body to create it in a disabled state.
      operationId: createWebhook
      requestBody:
        content:
          application/json:
            example:
              client_key_id: {}
              component_ids:
              - component_id
              component_references:
              - component_id: component_id
                socket_names:
                - socket_name
              default_method: default_method
              description: description
              enabled: true
              name: name
              request:
                body: body
                headers:
                  headers_key:
                  - headers_key
                method: method
                url: url
                urlTemplateParameters:
                  urlTemplateParameters_key: urlTemplateParameters_key
              response_body_handler:
                response_body_handler_key: {}
              response_handler: response_handler
              retry_intervals:
              - PT42S
              tags:
              - tag
              type: CLIENT
              url: url
            schema:
              $ref: '#/components/schemas/WebhookCreateRequest'
        description: WebhookCreateRequest object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                campaign_component_absolute_name_missing:
                  $ref: '#/components/examples/campaign_component_absolute_name_missing'
                campaign_component_description_out_of_range:
                  $ref: '#/components/examples/campaign_component_description_out_of_range'
                campaign_component_display_name_contains_illegal_character:
                  $ref: '#/components/examples/campaign_component_display_name_contains_illegal_character'
                campaign_component_display_name_out_of_range:
                  $ref: '#/components/examples/campaign_component_display_name_out_of_range'
                campaign_component_id_missing:
                  $ref: '#/components/examples/campaign_component_id_missing'
                campaign_component_name_already_in_use:
                  $ref: '#/components/examples/campaign_component_name_already_in_use'
                campaign_component_name_contains_illegal_character:
                  $ref: '#/components/examples/campaign_component_name_contains_illegal_character'
                campaign_component_name_out_of_range:
                  $ref: '#/components/examples/campaign_component_name_out_of_range'
                campaign_component_type_validation_failed:
                  $ref: '#/components/examples/campaign_component_type_validation_failed'
                circular_component_reference:
                  $ref: '#/components/examples/circular_component_reference'
                component_facets_not_found:
                  $ref: '#/components/examples/component_facets_not_found'
                excessive_component_reference:
                  $ref: '#/components/examples/excessive_component_reference'
                external_element_is_referenced_by_active_configuration:
                  $ref: '#/components/examples/external_element_is_referenced_by_active_configuration'
                external_elements_cannot_have_multiple_references:
                  $ref: '#/components/examples/external_elements_cannot_have_multiple_references'
                invalid_component_installed_into_socket:
                  $ref: '#/components/examples/invalid_component_installed_into_socket'
                invalid_component_reference:
                  $ref: '#/components/examples/invalid_component_reference'
                invalid_component_reference_socket_name:
                  $ref: '#/components/examples/invalid_component_reference_socket_name'
                invalid_external_component_reference:
                  $ref: '#/components/examples/invalid_external_component_reference'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                orphan_external_component_reference:
                  $ref: '#/components/examples/orphan_external_component_reference'
                redundant_component_reference:
                  $ref: '#/components/examples/redundant_component_reference'
                reward_supplier_webhook_filter_is_missing:
                  $ref: '#/components/examples/reward_supplier_webhook_filter_is_missing'
                reward_supplier_webhook_filter_not_found:
                  $ref: '#/components/examples/reward_supplier_webhook_filter_not_found'
                self_component_reference:
                  $ref: '#/components/examples/self_component_reference'
                unknown_webhook_type:
                  $ref: '#/components/examples/unknown_webhook_type'
                webhook_build_failed:
                  $ref: '#/components/examples/webhook_build_failed'
                webhook_client_key_not_found:
                  $ref: '#/components/examples/webhook_client_key_not_found'
                webhook_invalid_default_method:
                  $ref: '#/components/examples/webhook_invalid_default_method'
                webhook_invalid_description:
                  $ref: '#/components/examples/webhook_invalid_description'
                webhook_invalid_name:
                  $ref: '#/components/examples/webhook_invalid_name'
                webhook_invalid_tag:
                  $ref: '#/components/examples/webhook_invalid_tag'
                webhook_local_or_internal_url:
                  $ref: '#/components/examples/webhook_local_or_internal_url'
                webhook_malformed_url:
                  $ref: '#/components/examples/webhook_malformed_url'
                webhook_missing_name:
                  $ref: '#/components/examples/webhook_missing_name'
                webhook_missing_url:
                  $ref: '#/components/examples/webhook_missing_url'
                webhook_name_duplicate:
                  $ref: '#/components/examples/webhook_name_duplicate'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
                reward_supplier_not_found:
                  $ref: '#/components/examples/reward_supplier_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Create a webhook
      tags:
      - Webhooks
      x-extole-bundle: management
      x-extole-visibility: visible
  /v6/webhooks/built:
    get:
      description: 'Returns all webhooks in their fully evaluated (built) runtime form, with all evaluatable fields resolved. Supports finer filtering than the source list: `name`, `include_archived`, `limit`, and `offset` are only available on this endpoint. Use this when you need effective endpoint URLs and headers.'
      operationId: listBuiltWebhooks
      parameters:
      - in: query
        name: enabled
        schema:
          nullable: true
          type: boolean
      - in: query
        name: type
        schema:
          enum:
          - CLIENT
          - GENERIC
          - PARTNER
          - REWARD
          nullable: true
          type: string
      - in: query
        name: name
        schema:
          nullable: true
          type: string
      - in: query
        name: include_archived
        schema:
          nullable: true
          type: boolean
      - in: query
        name: limit
        schema:
          format: int32
          nullable: true
          type: integer
      - in: query
        name: offset
        schema:
          format: int32
          nullable: true
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/BuiltWebhookResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: List built webhooks
      tags:
      - Webhooks
      x-extole-bundle: management
      x-extole-visibility: visible
  /v6/webhooks/{webhook_id}:
    get:
      description: Returns the source definition of the supplied webhook, including its URL, headers, event filters, and state. Returns `400 webhook_not_found` if the id does not exist or is not accessible.
      operationId: getWebhook
      parameters:
      - in: path
        name: webhook_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
          description: Webhook definition.
        '400':
          content:
            application/json:
              examples:
                webhook_not_found:
                  $ref: '#/components/examples/webhook_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Webhook was not found. The supplied id does not match any webhook accessible to the calling client.
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get a webhook
      tags:
      - Webhooks
      x-extole-bundle: management
      x-extole-visibility: visible
    put:
      description: Applies a partial update to the supplied webhook. Only the fields present in the body are changed; omitted fields are left intact. Returns the persisted webhook after the update. Returns `400 webhook_not_found` if the id does not exist.
      operationId: updateWebhook
      parameters:
      - description: The id of the webhook to be updated.
        in: path
        name: webhook_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              client_key_id: {}
              component_ids:
              - component_id
              component_references:
              - component_id: component_id
                socket_names:
                - socket_name
              default_method: default_method
              description: description
              enabled: true
              name: name
              request:
                body: body
                headers:
                  headers_key:
                  - headers_key
                method: method
                url: url
                urlTemplateParameters:
                  urlTemplateParameters_key: urlTemplateParameters_key
              response_body_handler:
                response_body_handler_key: {}
              response_handler: response_handler
              tags:
              - tag
              url: url
            schema:
              $ref: '#/components/schemas/WebhookUpdateRequest'
        description: WebhookUpdateRequest object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
          description: Updated webhook.
        '400':
          content:
            application/json:
              examples:
                webhook_not_found:
                  $ref: '#/components/examples/webhook_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Webhook was not found. The supplied id does not match any webhook accessible to the calling client.
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
                reward_supplier_not_found:
                  $ref: '#/components/examples/reward_supplier_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Update a webhook
      tags:
      - Webhooks
      x-extole-bundle: management
      x-extole-visibility: visible
    delete:
      description: Archives (soft-deletes) the supplied webhook. The webhook stops firing immediately but its definition is retained. Fails with `400 webhook_associated_with_webhook_controller_action` if the webhook is referenced by a controller action, or `400 webhook_associated_with_webhook_user_subscription_channel` if it is referenced by a user subscription channel. Remove those references before archiving.
      operationId: archiveWebhook
      parameters:
      - description: The id of the webhook to be deleted.
        in: path
        name: webhook_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
          description: Archived webhook.
        '400':
          content:
            application/json:
              examples:
                webhook_associated_with_webhook_controller_action:
                  $ref: '#/components/examples/webhook_associated_with_webhook_controller_action'
                webhook_associated_with_webhook_user_subscription_channel:
                  $ref: '#/components/examples/webhook_associated_with_webhook_user_subscription_channel'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Cannot archive the webhook because it is still referenced by a webhook controller action or a user subscription channel. Remove those references first.
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Archive a webhook
      tags:
      - Webhooks
      x-extole-bundle: management
      x-extole-visibility: visible
  /v6/webhooks/{webhook_id}/built:
    get:
      description: Returns the fully evaluated (built) runtime form of the supplied webhook, with all evaluatable fields resolved. Returns `400 webhook_not_found` if the id does not exist or is not accessible.
      operationId: getBuiltWebhook
      parameters:
      - in: path
        name: webhook_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuiltWebhookResponse'
          description: Built webhook.
        '400':
          content:
            application/json:
              examples:
                webhook_not_found:
                  $ref: '#/components/examples/webhook_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Webhook was not found. The supplied id does not match any webhook accessible to the calling client.
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
                reward_supplier_not_found:
                  $ref: '#/components/examples/reward_supplier_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get a built webhook
      tags:
      - Webhooks
      x-extole-bundle: management
      x-extole-visibility: visible
components:
  schemas:
    RewardWebhookResponse:
      allOf:
      - $ref: '#/components/schemas/WebhookResponseBase'
      - properties:
          filters:
            items:
              $ref: '#/components/schemas/RewardWebhookFilterResponse'
            type: array
          id:
        

# --- truncated at 32 KB (124 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/extole/refs/heads/main/openapi/extole-webhooks-api-openapi.yml