openapi: 3.1.0
info:
  title: MessageBird Balance Available Numbers Webhooks API
  description: The MessageBird Balance API provides developers with access to their account balance information. It returns the current payment type, available amount, and currency for the account associated with the API key. This API is useful for monitoring credit usage, building billing dashboards, and setting up automated alerts when account balances fall below a threshold.
  version: '1.0'
  contact:
    name: MessageBird Support
    url: https://support.messagebird.com
  termsOfService: https://www.messagebird.com/en/terms
servers:
- url: https://rest.messagebird.com
  description: Production Server
security:
- accessKey: []
tags:
- name: Webhooks
  description: Operations for managing conversation webhooks that receive real-time event notifications.
paths:
  /webhooks:
    get:
      operationId: listWebhooks
      summary: List webhooks
      description: Retrieves a list of all configured conversation webhooks. The platform supports up to 10 channel-specific webhooks and 5 generic webhooks.
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: A list of webhooks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'
        '401':
          description: Unauthorized
    post:
      operationId: createWebhook
      summary: Create a webhook
      description: Creates a new webhook to receive real-time notifications for conversation events. Webhooks can be channel-specific or generic.
      tags:
      - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
      responses:
        '200':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /webhooks/{webhookId}:
    get:
      operationId: viewWebhook
      summary: View a webhook
      description: Retrieves the details of a specific webhook by its unique identifier.
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/webhookIdParam'
      responses:
        '200':
          description: Webhook details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          description: Unauthorized
        '404':
          description: Webhook not found
    patch:
      operationId: updateWebhook
      summary: Update a webhook
      description: Updates the configuration of an existing webhook.
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/webhookIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
      responses:
        '200':
          description: Webhook updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Webhook not found
    delete:
      operationId: deleteWebhook
      summary: Delete a webhook
      description: Deletes an existing webhook by its unique identifier.
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/webhookIdParam'
      responses:
        '204':
          description: Webhook deleted
        '401':
          description: Unauthorized
        '404':
          description: Webhook not found
    put:
      operationId: updateVoiceWebhook
      summary: Update a voice webhook
      description: Updates an existing voice webhook configuration.
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/webhookIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoiceWebhookCreate'
      responses:
        '200':
          description: Webhook updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceWebhookResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Webhook not found
components:
  parameters:
    limitParam:
      name: limit
      in: query
      required: false
      description: The maximum number of items to return.
      schema:
        type: integer
        default: 20
    webhookIdParam:
      name: webhookId
      in: path
      required: true
      description: The unique identifier of the webhook.
      schema:
        type: string
    offsetParam:
      name: offset
      in: query
      required: false
      description: The number of items to skip.
      schema:
        type: integer
        default: 0
  schemas:
    VoiceWebhook:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the webhook.
        url:
          type: string
          format: uri
          description: The URL that receives webhook callbacks.
        token:
          type: string
          description: The token used for signature validation.
        createdAt:
          type: string
          format: date-time
          description: The date and time when the webhook was created.
        updatedAt:
          type: string
          format: date-time
          description: The date and time when the webhook was last updated.
    VoiceWebhookResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/VoiceWebhook'
    Webhook:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the webhook.
        channelId:
          type: string
          description: The channel the webhook is subscribed to.
        url:
          type: string
          format: uri
          description: The URL that receives webhook payloads.
        events:
          type: array
          description: The events the webhook is subscribed to.
          items:
            type: string
        status:
          type: string
          description: The status of the webhook.
          enum:
          - enabled
          - disabled
        createdDatetime:
          type: string
          format: date-time
          description: The date and time when the webhook was created.
        updatedDatetime:
          type: string
          format: date-time
          description: The date and time when the webhook was last updated.
    VoiceWebhookCreate:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
          description: The URL to receive webhook callbacks.
        token:
          type: string
          description: A token for webhook signature validation.
    WebhookCreate:
      type: object
      required:
      - channelId
      - url
      - events
      properties:
        channelId:
          type: string
          description: The channel to subscribe to. Omit for a generic webhook that receives events from all channels.
        url:
          type: string
          format: uri
          description: The URL to receive webhook payloads.
        events:
          type: array
          description: The list of events to subscribe to.
          items:
            type: string
            enum:
            - message.created
            - message.updated
            - conversation.created
            - conversation.updated
    WebhookList:
      type: object
      properties:
        offset:
          type: integer
          description: The offset of the result set.
        limit:
          type: integer
          description: The limit applied to the result set.
        count:
          type: integer
          description: The number of items returned.
        totalCount:
          type: integer
          description: The total number of webhooks.
        items:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'
  securitySchemes:
    accessKey:
      type: apiKey
      in: header
      name: Authorization
      description: Access key authentication in the form of 'AccessKey {accessKey}'.
externalDocs:
  description: Balance API Documentation
  url: https://developers.messagebird.com/api/balance/