Update Webhook (Transactional SMS)

Overview

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

Endpoint

Method	URL
PUT	https:// {{your_url}} /api/2.0/production/sms/webhooks/{{webhook_id}}

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	Must be an array
url		This is the URL of the webhook that the data will be passed to	String		Must be a string
verb		This is the method that is used for data requesting and receiving data	String	POST GET	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

Full body – changes all data in the webhook

{
    "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"
    }
}

Specific changes to body – updates status to disabled and event_types to “reply” and “bounce”

{
    "webhook": {
        "event_types": [
            "reply",
            "bounce"
        ],
        "status": "disabled"
    }
}

Example Curl Request

curl --location  --request PUT 'https://{{your_url}}/api/2.0/production/sms/webhooks/{{webhook_id}}' \
--data '{
    "webhook": {
        "event_types": [
            "reply",
            "bounce"
        ],
        "status": "disabled"
    }
}'

Responses

Status Code	Explanation
200 OK	Webhook was updated 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

Status Code

Explanation

200 OK

Webhook was updated 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": [
            "reply",
            "bounce"
        ],
        "status": "disabled"
    }
}

Response Body Example

{
    "status": "success",
    "data": {
        "webhook": {
            "id": "4e54180d-597e-4e24-b712-862f04d385ad",
            "url": "https://typedwebhook.tools/webhook/01b81007-8edb-43f8-ae20-7af088ace8f7",
            "verb": "post",
            "auth_details": null,
            "auth_type": null,
            "status": "disabled",
            "updated_timestamp": "2023-09-13T17:31:47+02:00",
            "created_timestamp": "2023-09-13T12:03:39+02:00",
            "event_types": [
                "reply",
                "bounce"
            ]
        }
    }
}

400 Bad Request

Request Body Example

Invalid body (status value incorrect)

{
    "webhook": {
        "event_types": [
            "reply",
            "test"
        ],
        "status": "active"
    }
}

Response Body Example

{
    "status": "error",
    "data": "The payload for the webhook is not in the correct format. {\"webhook.status\":[\"The selected webhook.status is invalid, status should only be enabled or disabled.\"]}"
}

401 Unauthorized

Response Body Example

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

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

Example Request Body

If status is given a number where a string is expected

{
    "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": 123
    }
}

Example Response Body

{
    "status": "error",
    "data": "The payload for the webhook is not in the correct format. {\"webhook.status\":[\"validation.string\"]}"
}

Required Validation

Example Request Body

{
    "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 Body

{
    "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

Example Request Body

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"
    }
}

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 Body

Missing auth_details

{
    "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.\"]}"
}

Missing auth_details.password

{
    "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.\"]}"
}