Update Transactional WhatsApp Webhook Settings with OAuth 2.0

You can use this API to update webhooks and other settings for transactional WhatsApp messages.

To send transactional WhatsApp messages using OAuth 2.0, you must first generate an OAuth 2.0 credential. For step-by-step instructions, refer to OAuth 2.0 Credentials.

Endpoint

POST https://gw.useinsider.com/api/wa/v2/transactional/settings

Visit our Postman collection to test this request.

Parameter	Type	Required	Description
webhook_url	string	Yes	Partner webhook URL (must be a valid URL)
from	string	No	Sender phone number. If left empty, the default provider is used.
auth_type	string	Yes	Authentication type: "bearer" or "oauth2"
api_key	string	Conditional	Required if auth_type is "bearer"
oauth2	object	Conditional	Required if auth_type is "oauth2"
oauth2.grant_type	string	Yes	"client_credentials" or "refresh_token"
oauth2.token_url	string	Yes	OAuth2 token endpoint URL
oauth2.client_id	string	Yes	Client ID
oauth2.client_secret	string	Yes	Client secret (stored encrypted)
oauth2.refresh_token	string	Conditional	Required if oauth2.grant_type is "refresh_token"
oauth2.scopes	array	No	OAuth2 scopes
oauth2.expires_in	integer	Yes	Token validity duration in seconds (must be > 0)

The system supports two grant types for OAuth2 authentication:

client_credentials
refresh_token

Client Credentials Request

curl -X POST "https://gw.useinsider.com/api/wa/v2/transactional/settings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "webhook_url": "https://partner.example.com/webhooks/transactional",
    "from": "+1234567890",
    "auth_type": "oauth2",
    "oauth2": {
      "grant_type": "client_credentials",
      "token_url": "https://oauth.partner.com/oauth/token",
      "client_id": "your_client_id",
      "client_secret": "your_client_secret",
      "scopes": [
        "webhook.write"
      ],
      "expires_in": 3600
    }
  }'

Your system must respond with a 200 OK status to our request for the webhook to be saved and function correctly. If you receive any response other than 200 from the settings endpoint, it indicates an issue with the URL you provided. Please review the error message returned and verify your endpoint accordingly.

Refresh Token Request

curl -X POST "https://gw.useinsider.com/api/wa/v2/transactional/settings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "webhook_url": "https://partner.example.com/webhooks/transactional",
    "from": "+1234567890",
    "auth_type": "oauth2",
    "oauth2": {
      "grant_type": "refresh_token",
      "token_url": "https://oauth.partner.com/oauth/token",
      "client_id": "your_client_id",
      "client_secret": "your_client_secret",
      "refresh_token": "your_refresh_token",
      "scopes": [
        "webhook.write"
      ],
      "expires_in": 3600
    }
  }'

Error Codes

Code	HTTP Status	Description
2010	400	The settings request body could not be decoded.
2011	400	The settings request body failed validation.
2012	400	An error occurred while saving the settings.
2020	400	The webhook URL failed validation.