SMSHook

Overview

Receive asynchronous SMS event notifications from SMSHook at your webhook endpoint.

Current implementation details:

The callback flow is:

An SMS event occurs.
SendCloud builds callback parameters from the internal event payload.
SendCloud sends an application/x-www-form-urlencoded POST request to your configured URL.
Your server parses the form fields and returns an HTTP success status.
If the callback fails or times out, SendCloud retries according to the retry policy below.

SMSHook currently forwards these events:

Configure your endpoint to meet these requirements:

The current implementation also applies these rules:

The current sender implementation treats any HTTP status in the range 200-209 as success.
The response body is not used by the sender.
The sender timeout is configured by retry sequence:
- First attempt: about 5s
- Second attempt: about 10s
- Later attempts: up to 15s
The current sender implementation does not include a GET probe flow.

Each callback includes:

Generate the signature with:

signature = HMAC_SHA256(appKey, timestamp + token)

Use your SMSHook APP KEY / API key as appKey.

Current retry configuration:

Use these field conventions when you parse callback data:

All callback values are sent as form field strings.
smsIds and phones are JSON-array text values inside form fields.
custom_args is the actual callback field name.
Template-review fields are spelled exactly as:
- verfiyResult
- verfiyComment

Fields marked as optional may be omitted or be empty, depending on source data.

Triggered when an SMS request is accepted.

Field	Type	Required	Notes
`event`	`string`	Yes	Always `Requested`
`eventType`	`int`	Yes	Always `1`
`userId`	`int`	Yes	User ID
`timestamp`	`long`	Yes	Event timestamp
`token`	`string`	Yes	Random 50-character token
`signature`	`string`	Yes	HMAC-SHA256 signature
`templateId`	`int`	Yes	Defaults to `0` if source value is absent
`smsUser`	`string`	No	SMS user
`msgCount`	`int`	No	Present only when source value exists
`message`	`string`	Yes	Defaults to `request`
`smsIds`	`string`	No	JSON array text, for example `["msgid$13800000000"]`
`phones`	`string`	No	JSON array text, for example `["13800000000"]`
`custom_args`	`string`	No	JSON text or plain string

Triggered when an SMS is delivered.

Field	Type	Required	Notes
`event`	`string`	Yes	Always `Delivered`
`eventType`	`int`	Yes	Always `20`
`userId`	`int`	Yes	User ID
`timestamp`	`long`	Yes	Event timestamp
`token`	`string`	Yes	Random 50-character token
`signature`	`string`	Yes	HMAC-SHA256 signature
`templateId`	`int`	Yes	Defaults to `0` if source value is absent
`smsUser`	`string`	No	SMS user
`msgCount`	`int`	No	Present only when source value exists
`phone`	`string`	No	Recipient phone number
`smsId`	`string`	No	SMS ID
`message`	`string`	No	Delivery message
`receiptTime`	`string`	Yes	Generated from timestamp, format `yyyy-MM-dd HH:mm:ss`
`outboundTime`	`string`	No	Loaded from status data when available
`custom_args`	`string`	No	JSON text or plain string

Triggered when an SMS is suppressed.

Field	Type	Required	Notes
`event`	`string`	Yes	Always `Suppressed`
`eventType`	`int`	Yes	Always `4`
`userId`	`int`	Yes	User ID
`timestamp`	`long`	Yes	Event timestamp
`token`	`string`	Yes	Random 50-character token
`signature`	`string`	Yes	HMAC-SHA256 signature
`templateId`	`int`	Yes	Defaults to `0` if source value is absent
`smsUser`	`string`	No	SMS user
`msgCount`	`int`	No	Present only when source value exists
`phone`	`string`	No	Recipient phone number
`smsId`	`string`	No	SMS ID
`statusCode`	`int`	No	May be empty if no mapping is found
`message`	`string`	No	Suppression message
`encodeMessage`	`string`	No	Base64-encoded message
`outboundTime`	`string`	Yes	Generated from timestamp, format `yyyy-MM-dd HH:mm:ss`
`custom_args`	`string`	No	JSON text or plain string

Triggered when SMS delivery fails.

Field	Type	Required	Notes
`event`	`string`	Yes	Always `Failed`
`eventType`	`int`	Yes	Always `5`
`userId`	`int`	Yes	User ID
`timestamp`	`long`	Yes	Event timestamp
`token`	`string`	Yes	Random 50-character token
`signature`	`string`	Yes	HMAC-SHA256 signature
`templateId`	`int`	Yes	Defaults to `0` if source value is absent
`smsUser`	`string`	No	SMS user
`msgCount`	`int`	No	Present only when source value exists
`phone`	`string`	No	Recipient phone number
`smsId`	`string`	No	SMS ID
`statusCode`	`int`	No	May be empty if no mapping is found
`message`	`string`	No	Failure message
`encodeMessage`	`string`	No	Base64-encoded message
`receiptTime`	`string`	Yes	Generated from timestamp, format `yyyy-MM-dd HH:mm:ss`
`outboundTime`	`string`	No	Loaded from status data when available
`custom_args`	`string`	No	JSON text or plain string

Triggered when template review finishes.

Field	Type	Required	Notes
`event`	`string`	Yes	Always `Template Verify`
`eventType`	`int`	Yes	Always `8`
`userId`	`int`	Yes	User ID
`timestamp`	`long`	Yes	Event timestamp
`token`	`string`	Yes	Random 50-character token
`signature`	`string`	Yes	HMAC-SHA256 signature
`templateId`	`int`	Yes	Template ID
`name`	`string`	Yes	Template name
`verfiyResult`	`int`	No	Current implementation commonly uses `0` reviewing, `1` approved, `-1` rejected
`verfiyComment`	`string`	No	Present for rejected cases when available

Parse the callback body as form data, not JSON.
If you need structured values from smsIds, phones, or custom_args, parse the field value as JSON in your application.
Use the exact callback field names shown above.
Return 200 OK for successful processing.