Skip to Content
SMS APIHow to Setup SMS WebhookShortcode Inbox SMS Webhook

Shortcode Inbox SMS Webhook

We use HTTP callback (webhook) to forward incoming inbox messages directly to your application. If you do not have any SMS Shortcode, click here  to learn more.

Click organizations (business account) from the navigation menu

Click business account from the navigation menu

Click an organization/account assigned to short code of interest.

Click an account assigned to short code of interest

Click on the short codes tab.

Name the API Key appropriately

Click on the edit button.

Click on the edit button

Provide your forwarding url and submit.

Provide your forwarding url and submit

Example JSON payload

{ "id": 121, "api_date": "2021-04-10T15:04:00Z", "insert_date": "2021-04-10T15:05:00Z", "message": "Greetings, I’m happy to be here!", "sender": "+254700000002", "short_code": "110011", "retries": 0 }
id Unique id for the inbox message.
api_date Time the message reached SMSLeopard (RFC 3339).
insert_date Time the message was saved (RFC 3339). May include fractional seconds and a UTC offset.
message Received message.
sender Sender phone number.
short_code Shortcode that received the message.
retries Number of retries at forwarding the inbox message.

Endpoint requirements

Your forwarding URL must:

  • Accept an HTTP POST with a JSON body, sent with the headers Content-Type: application/json and User-Agent: SMSLeopard.
  • Return a 2xx status, such as 200 OK, within 10 seconds. Any other status, a redirect, or no reply counts as a failure.
  • Use a publicly reachable http or https URL. For https, the server must present a valid certificate with its full chain, including intermediate certificates. Browsers often fill in a missing intermediate, so a URL that opens in a browser can still fail here.
  • Not block requests from servers. A firewall or bot filter that only allows browsers will reject callbacks.

Failed deliveries are retried with an increasing delay, up to 7 attempts per message. The retries field in the payload tells you which attempt you are receiving.

Test your endpoint before saving it:

curl -i -X POST https://example.com/your-callback \ -H "Content-Type: application/json" \ -H "User-Agent: SMSLeopard" \ -d '{"id":1,"message":"test","sender":"+254700000000","short_code":"TEST","retries":0}'

You should get a 2xx response with no certificate error. To check the certificate chain, run your domain through SSL Labs  and make sure it does not report “Chain issues”.

Troubleshooting failed deliveries

Recent delivery attempts and their errors are listed under Recent deliveries on the short code.

ErrorMeaning
callback TLS certificate not trusted (incomplete chain or unknown issuer)Your server’s certificate chain is incomplete or not issued by a trusted authority. Install the full chain.
callback TLS certificate does not match hostThe certificate is for a different domain than the forwarding URL.
callback TLS certificate invalid or expiredThe certificate is expired or otherwise invalid.
callback request failedThe secure connection or the request failed for another reason.
callback request timed outYour endpoint did not reply within 10 seconds.
callback connection failedWe could not connect: the server is down, the port is closed, or a firewall blocked us.
callback DNS unavailableThe domain name in the forwarding URL does not resolve.
callback address is not publicThe domain resolves to a private or internal address.
invalid callback URLThe URL is malformed, or uses an unsupported scheme, port, or credentials.
HTTP 403, HTTP 500, …Your server or firewall answered with that error status.
delivery expired after 7 daysThe message could not be delivered within 7 days.