Overview

Call this endpoint as a POST request to register a webhook using the URL that you have provided in the body.

Endpoint

Method URL
POST

https:// {{your_url}} /api/2.0/production/sms/webhooks/create

Properties

Property

Sub-Property

Description

Data Type

Parameters

Validation Rules

event_types

These are the types of events that you are able to track from the transactional SMS

Array
  • Sent
  • Failed
  • Bounce
  • Reply
  • Delivered
  • Required
  • Must be an array

url

This is the URL of the webhook that the data will be passed to

String
  • Required
  • Must be a string

verb

This is the method that is used for data requesting and receiving data

String
  • POST
  • GET
  • Required
  • Must be a string

auth_details

This is an array of authentication details, if the webhook needs basic authentication

Array
  • Conditionally required based on if auth_type is basic
  • Must be an array only if there are authentication details

auth_details

username

This is the username required if the webhook has authentication

String
  • Conditionally required based on if auth_type is basic
  • Must be an string

auth_details

password

This is the password required if the webhook has authentication

String
  • Conditionally required based on if auth_type is basic
  • Must be an string

auth_type

This field is used to select the authentication type of the webhook

String

basic
  • This value must be string
  • This is not required if the webhook does not required authentication

status

This field is used to set if the webhook is enabled or disabled

String
  • enabled
  • disabled
  • This must be a string
  • If this value is not added, webhook will be enabled by default

Requests

Request Body Example
{
    "webhook": {
        "event_types": [
            "sent"
        ],
        "verb": "POST",
        "url": "https://webhook.site/f0fc8147-0a1a-4e6b-b070-b872812d6649",
        "auth_details": {
            "username": "username",
            "password": "password"
        },
        "auth_type": "basic",
        "status": "enabled"
    }
}
Example Request
curl --location 'https://{{your_url}}/api/2.0/production/sms/webhooks/create' \
--data '{
    "webhook": {
        "event_types": [
            "sent"
        ],
        "verb": "POST",
        "url": "https://webhook.site/f0fc8147-0a1a-4e6b-b070-b872812d6649",
        "auth_details": {
            "username": "username",
            "password": "password"
        },
        "auth_type": "basic",
        "status": "enabled"
    }
}'

Responses

Status Code

Explanation
200 OK

Webhook was created successfully

400 Bad Request

The request body was formatted improperly.

If there are keys missing, then the message returned will let you know that the request body was not formatted properly as well as what is missing or what is incorrect.

401 Unauthorized

The provided authorization credentials are incorrect

200 OK

Request Body Example
{
    "webhook": {
        "event_types": [
            "sent"
        ],
        "verb": "POST",
        "url": "https://webhook.site/f0fc8147-0a1a-4e6b-b070-b872812d6649",
        "auth_details": {
            "username": "administrator",
            "password": "password"
        },
        "auth_type": "basic",
        "status": "enabled"
    }
}
Example Response
{
    "status": "success",
    "data": {
        "webhook": {
            "id": "9edf82f9-fb6b-4427-a494-919957d17b3b",
            "url": "https://webhook.site/f0fc8147-0a1a-4e6b-b070-b872812d6649",
            "verb": "POST",
            "auth_details": {
                "username": "administrator",
                "password": "password"
            },
            "auth_type": "basic",
            "status": "enabled",
            "updated_timestamp": "2023-09-12T12:05:49+02:00",
            "created_timestamp": "2023-09-12T12:05:49+02:00",
            "event_types": [
                "sent"
            ]
        }
    }
}

400 Bad Request

Request Body Example
Invalid body (missing event_types)
{
    "webhook": {
        "verb": "POST",
        "url": "https://webhook.site/f0fc8147-0a1a-4e6b-b070-b872812d6649",
        "auth_details": {
            "username": "administrator",
            "password": "password"
        },
        "auth_type": "basic",
        "status": "enabled"
    }
}
Example Response
{
    "status": "error",
    "data": "The payload for the webhook is not in the correct format. {\"webhook.event_types\":[\"The webhook.event types field is required.\"]}"
}

401 Unauthorized

Example Response
"Invalid credentials."

Validation Errors

Status Code

Explanation

Data Type Validation

If a field is given data of the incorrect type, such as status, the response will return an error status with data that shows which field is the issue and what the data type should be.

Required Validation

If a field is required, but is missing from the request body, then the response will return an error and return a message that lets you know which field is missing, and is required.

In this case the verb key is missing and will produce an error message with information that the webhook.verb field is missing and is required.

Conditionally Required Validation

If the field is conditionally required, then it means that the field is required only if it meets a specific requirement

In this case, auth_details , auth_details.username and auth_details.password fields are conditionally required if auth_type is basic

Data Type Validation

Request Body Example
{
    "webhook": {
        "event_types": [
            "sent"
        ],
        "verb": "POST",
        "url": "https://webhook.site/f0fc8147-0a1a-4e6b-b070-b872812d6649",
        "auth_details": {
            "username": "administrator",
            "password": "password"
        },
        "auth_type": "basic",
        "status": 123
    }
}
Example Response
{
    "status": "error",
    "data": "The payload for the webhook is not in the correct format. {\"webhook.status\":[\"validation.string\"]}"
}

Required Validation

Request Body Example
{
    "webhook": {
        "event_types": [
            "sent"
        ],
        "url": "https://webhook.site/f0fc8147-0a1a-4e6b-b070-b872812d6649",
        "auth_details": {
            "username": "administrator",
            "password": "password"
        },
        "auth_type": "basic",
        "status": "enabled"
    }
}
Example Response
{
    "status": "error",
    "data": "The payload for the webhook is not in the correct format. {\"webhook.verb\":[\"The webhook.verb field is required.\"]}"
}

Conditionally Required Validation

Request Body Example (If the entire auth_details key is missing)
{
    "webhook": {
        "event_types": [
            "sent"
        ],
        "verb": "POST",
        "url": "https://webhook.site/f0fc8147-0a1a-4e6b-b070-b872812d6649",
        "auth_type": "basic",
        "status": "enabled"
    }
}
Request Body Example (Or if only username or password field is missing)
{
    "webhook": {
        "event_types": [
            "sent"
        ],
        "verb": "POST",
        "url": "https://webhook.site/f0fc8147-0a1a-4e6b-b070-b872812d6649",
        "auth_details": {
            "username": "administrator"
        },
        "auth_type": "basic",
        "status": "enabled"
    }
}
Example Response
{
    "status": "error",
    "data": "The payload for the webhook is not in the correct format. {\"webhook.auth_details\":[\"The webhook.auth details field is required when webhook.auth type is basic.\"]}"
}
Example Response
{
    "status": "error",
    "data": "The payload for the webhook is not in the correct format. {\"webhook.auth_details.password\":[\"The webhook.auth details.password field is required when webhook.auth type is basic.\"]}"
}