Skip to main content

Subscribe to webhooks

POST 

/api/v1/webhooks/subscribe

Subscribe to receive webhooks for what happens in your HelloSMS account. There are four kinds, set with type: INCOMING_MESSAGE (every incoming message), INCOMING_SMS (deprecated: incoming SMS only, use INCOMING_MESSAGE), SIGNOFF (a recipient opts out) and EVENTS (something happens to a message you sent, such as a recipient clicking a link). For EVENTS, also choose which events and which messages you want. See the Incoming message webhook page for INCOMING_MESSAGE and INCOMING_SMS, the Opt-out webhook page for SIGNOFF and the Events webhook page for EVENTS.

Request​

Body

Information needed to subscribe to the webhook.

    hookUrlstring

    The URL of your webhook endpoint, where HelloSMS will send event notifications. It must be a public web address; an address inside a private network is refused.

    Possible values: <= 2048 characters

    typestring

    Specifies the kind of webhook: INCOMING_MESSAGE (every incoming message), INCOMING_SMS (deprecated: incoming SMS only, use INCOMING_MESSAGE), SIGNOFF (recipient opt-out) or EVENTS (something happens to a message you sent, such as a link click).

    events object

    Required when type is EVENTS. Which events you want: the string all, or a list such as ["LINK_CLICK"]. all also covers event types added later. See Events webhook for the events and their format. Ignored for other types.

    oneOf
    string

    Possible values: [all]

    messagesstring

    Only for EVENTS. Which messages the events are sent for: all (every message your account sends, including from the web app) or api (only messages sent through the API). Ignored for other types.

    Possible values: [all, api]

    Default value: all
    channelsstring[]

    Only for INCOMING_MESSAGE: the channels to receive replies from, sms and/or rcs. Leave it out to receive every channel. Subscribing again with a different list replaces the channels. Other types refuse it.

    Possible values: [sms, rcs]

Responses​

The webhook subscription was successful. If you subscribe to the same hookUrl and type again, the response is Webhook already subscribed with the existing webhookId. For INCOMING_MESSAGE with a different channels list, the channels are replaced and the response is Webhook channels updated. For EVENTS, subscribing again with the same hookUrl but different events or messages replaces the earlier choices and replies Webhook subscribed successfully.