SMSHook

Overview

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

Current implementation details:

• Sends callbacks only by POST.
• Sends form fields, not a JSON request body.
• Treats HTTP status codes 200 through 209 as success.
• Ignores the response body.
• Retries failed deliveries according to the configured retry schedule.
• Currently forwards only these event types: 1, 20, 4, 5, 8.

Delivery Flow

The callback flow is:

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

Supported Events

SMSHook currently forwards these events:

Delivery Format and Endpoint Requirements

Configure your endpoint to meet these requirements:

• Accept POST requests.
• Parse application/x-www-form-urlencoded request bodies.
• Return HTTP 200 OK on success.
• Respond quickly.

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.

Signature Verification

Each callback includes:

• token: a random 50-character string.
• timestamp: the event timestamp.
• signature: a lowercase hex HMAC-SHA256 value.

Generate the signature with:

signature = HMAC_SHA256(appKey, timestamp + token)

Use your SMSHook APP KEY / API key as appKey.

Retry Behavior

Current retry configuration:

• Initial delivery + 7 retries
• Retry intervals:
  • 3m
  • 10m
  • 30m
  • 1h
  • 6h
  • 12h
  • 24h

Field Conventions

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

Event Reference

Event Reference

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

Requested (eventType = 1)

Triggered when an SMS request is accepted.

Delivered (eventType = 20)

Triggered when an SMS is delivered.

Suppressed (eventType = 4)

Triggered when an SMS is suppressed.

Failed (eventType = 5)

Triggered when SMS delivery fails.

Template Verify (eventType = 8)

Triggered when template review finishes.

Integration Notes

• 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.