BulkSMS Webhooks API

openapi: 3.2.0
info:
  title: BulkSMS JSON REST Webhooks API
  version: 1.1.0
  x-logo:
    url: /developer/images/bulksms-logo-main.svg
    backgroundColor: '#FFFFFF'
  description: '## Overview


    The JSON REST API allows you to submit and receive BulkSMS messages.'
servers:
- url: https://api.bulksms.com/v1
  description: Production
security:
- basicAuth: []
tags:
- name: Webhooks
  description: 'Manage webhooks that notify your server when messages are sent or received.


    For full details on implementing your webhook — including event types, request headers, payload structure, retry logic, and testing — see the Webhook Developer Guide.'
paths:
  /webhooks:
    get:
      tags:
      - Webhooks
      operationId: webhook.list
      summary: List webhooks
      description: Returns a list of webhooks that have been created for this account. See the Webhook Developer Guide for event types, payload structure, and implementation details.
      responses:
        '200':
          description: An array of Webhook objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
    post:
      tags:
      - Webhooks
      operationId: webhook.create
      summary: Create a webhook
      description: 'A webhook is a URL that you can register when you want the BulkSMS system to notify you about your messages.

        You can register multiple webhooks, and each one will be called. (Note: you can also use our Web App to manage your webhooks interactively.)

        If you want to be notified of `SENT` messages and `RECEIVED` messages you need to create two webhooks.


        See the Webhook Developer Guide for event types, payload structure, implementation details, and testing instructions.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEntry'
      responses:
        '200':
          description: Contains the webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/bad-webhook-url'
  /webhooks/{id}:
    get:
      tags:
      - Webhooks
      operationId: webhook.show
      summary: Read a webhook
      description: Returns a specific webhook. See the Webhook Developer Guide for event types, payload structure, and implementation details.
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A Webhook object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/bad-webhook-url'
        '404':
          $ref: '#/components/responses/bad-webhook-id'
    post:
      tags:
      - Webhooks
      operationId: webhook.update
      summary: Update a webhook
      description: Updates the webhook. See the Webhook Developer Guide for event types, payload structure, and implementation details.
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEntry'
      responses:
        '200':
          description: Contains the updated webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/bad-webhook-url'
        '404':
          $ref: '#/components/responses/bad-webhook-id'
    delete:
      tags:
      - Webhooks
      operationId: webhook.delete
      summary: Delete a webhook
      description: Deletes a specific webhook. See the Webhook Developer Guide for event types, payload structure, and implementation details.
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The webhook has been deleted.
        '404':
          $ref: '#/components/responses/bad-webhook-id'
components:
  responses:
    bad-webhook-id:
      description: A webhook with the given id does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            type: https://developer.bulksms.com/json/v1/errors/#not-found
            title: Not Found
            status: 404
            detail: 'Webhook with id ''1'' does not exist

              '
    bad-webhook-url:
      description: The url given for the webhook is not callable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            type: https://developer.bulksms.com/json/v1/errors/#bad-request
            title: Bad Request
            status: 400
            detail: 'Invoking the Webhook URL caused an error: 403 - Forbidden

              '
  schemas:
    Webhook:
      type: object
      properties:
        id:
          type: number
          example: 234
        name:
          type: string
          example: My MT Webhook
        url:
          type: string
          example: https://www.example.com
        contactEmailAddress:
          type: string
          example: tech_team@example.com
        triggerScope:
          type: string
          example: SENT
        active:
          type: boolean
          example: true
        onWebApp:
          type: boolean
          example: true
    WebhookEntry:
      type: object
      required:
      - name
      - url
      - triggerScope
      properties:
        name:
          type: string
          example: My MT Webhook
          description: 'A text identifier for the webhook.

            More than one webhook cannot have the same name.

            '
        url:
          type: string
          example: https://www.example.com
          description: 'The location of the webhook.


            In addition to being a [valid URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier#Syntax), the url must also start with `http` or `https`.

            '
        contactEmailAddress:
          type: string
          example: tech_team@example.com
          description: 'The email address to which emails will be sent if there are problem with invoking the webhook.


            The value must be a valid email address.

            If this value is `null`, no email will be sent.


            It is `null` by default.

            '
        triggerScope:
          type: string
          enum:
          - SENT
          - RECEIVED
          description: 'Specifies when the webhook will be triggered.


            Please note the values are case sensitive.


            If the value is `SENT`, the webhook will be called when a status update becomes available for a message you sent (i.e. a mobile terminating (MT) message).


            If the value is `RECEIVED`, the webhook will be called when a message is received (i.e. a mobile originating (MO) message).


            Note that this field forces you to create two separate webhook entries if you want to collect all messages.  However,  you can use the same `url` for both webhooks if you want.

            '
          example: SENT
        invokeOption:
          type: string
          enum:
          - ONE
          - MANY
          description: 'Specifies how to invoke your webhook.


            If the value is `ONE` the array POSTed to your webhook will contain no more than a single message.  Use this option if your webhook logic is unable to handle more than one messages at a time.


            If the value is `MANY` the array POSTed to your webhook can contain up to 10 messages.  This is the recommended option.  The number of calls made to your webhook would be less and this will speed up your total processing time.

            If your webhook fails for an invoke that has more than one message, each message in the array will automatically be retried one at a time.


            This value defaults to `ONE` - but it is recommended that you set this property to `MANY`.

            '
          example: MANY
        active:
          type: boolean
          description: 'Indicates whether you want the webhook activated.


            If the value is `true`, the webhook at the given `url` will be invoked with an empty array (`[]`) as part of the validation process.

            If the webhook responds with a `2xx` status code, the submission is accepted; if not the webhook is not created (or updated).


            If the value is `false` the webhook will be inactive, and it will not be invoked when messages are `SENT` or `RECEIVED`.


            The default value is `true`.

            '
          example: true
        onWebApp:
          type: boolean
          example: true
          description: 'Indicates whether you want to show this webhook on the Web App.


            Webhooks shown there can be updated by the user that use the public Web site.


            The default value is `true`.

            '
    Error:
      description: See the errors page at https://www.bulksms.com/developer/json/v1/errors/ for more detail on what kind of errors you can get.
      type: object
      required:
      - type
      - title
      - status
      properties:
        type:
          description: A URL to one of the error types listed at https://www.bulksms.com/developer/json/v1/errors/
          type: string
        title:
          description: A short description of the type
          type: string
        status:
          description: The HTTP status code
          type: integer
          format: int32
          example: 400
        detail:
          description: More information about why the error occurred.
          type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'The API uses HTTP Basic Auth with an **API Token** for authentication.


        API tokens can be created by logging into your account and visiting _Settings > Developer Settings > API Tokens_.


        Supply the token ID as the username and the token secret as the password. The values must be [Base64 encoded](https://en.wikipedia.org/wiki/Base64) before using them in the `Authorization` header.


        For example, if the token ID is `BBDE1B476E03498AA768F66A286AABDC-01-B` and the token secret is `9jSbVDK20!MXdfRGiIIFu#ffUE8*S`, the unencoded header value is `BBDE1B476E03498AA768F66A286AABDC-01-B:9jSbVDK20!MXdfRGiIIFu#ffUE8*S`.  After encoding, the full header becomes


        ```

        Authorization: Basic QkJERTFCNDc2RTAzNDk4QUE3NjhGNjZBMjg2QUFCREMtMDEtQjo5alNiVkRLMjAhTVhkZlJHaUlJRnUjZmZVRTgqUw==

        ```


        You are requested to preemptively provide the `Authorization` header in your requests and not wait until the server has provided a `401 Unauthorized` response. Doing so will reduce the number of requests required to achieve your goal, which will improve overall performance.


        > **Username and password authentication is no longer supported.** Accounts created after 2026-04-29 can only authenticate with an API token. If you have a legacy integration that cannot be switched to token-based authentication, please [contact Support](https://www.bulksms.com/contact/) to request an exemption.

        '