Skip to content
API Documentation

Incoming SMS (MO)

POST
/your-webhook-url/mo
curl --request POST \
  --url https://api.contacta.mx/your-webhook-url/mo \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: contacta.mx' \
  --header 'x-contacta-signature: b6589fc6ab0dc82cf12099d1c2d40ab994e8410c' \
  --header 'x-contacta-time: 1750000000' \
  --header 'x-contacta-user: a94a8fe5ccb19ba61c4c0873d391e987982fbbd3' \
  --data '{ "source_addr": "5218112345678", "message": "Hola, quiero más información", "sms_id": "MT-9f3a1b7c2d" }'

Contacta.mx sends a POST request to your configured webhook URL when an inbound SMS message (Mobile Originated) is received.

This is not an endpoint you call — configure your webhook URL through request to soporte@contacta.mx and implement this endpoint on your server to receive incoming messages.

Validating requests

Every webhook request includes the following headers to verify it originates from contacta.mx:

Header Value
User-Agent contacta.mx
x-contacta-time Unix timestamp (seconds)
x-contacta-user sha1(api_key)
x-contacta-signature sha1(api_key + x-contacta-time)

Reject requests where the signature does not match or where x-contacta-time is older than your acceptable tolerance window (e.g. 60 seconds).

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
User-Agent
required
string
Allowed values: contacta.mx
Example
contacta.mx

Always set to contacta.mx on webhook requests

x-contacta-time
required
integer
Example
1750000000

Unix timestamp (seconds) of when the request was sent.

Use this together with x-contacta-signature to validate request freshness and prevent replay attacks.

x-contacta-user
required
string
Example
a94a8fe5ccb19ba61c4c0873d391e987982fbbd3

SHA1 hash of your API key.

Use this to identify which account sent the webhook.

x-contacta-signature
required
string
Example
b6589fc6ab0dc82cf12099d1c2d40ab994e8410c

SHA1 hash of your API key concatenated with the timestamp from x-contacta-time.

Use this to verify the request authenticity:

expected = sha1(api_key + x-contacta-time)
valid    = expected == x-contacta-signature

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Payload delivered to your webhook URL when an incoming SMS (MO) is received.

Either sms_id or short_code will be present depending on your account configuration:

  • sms_id — when the message was received on a shared short code
  • short_code — when the message was received on a dedicated short code
object
source_addr
required

Phone number of the person who sent the message (E.164 without +)

string
message
required

Text content of the incoming SMS

string
sms_id

Originating MT message ID. Present when the reply was received on a shared short code. Identifies which outgoing message this reply corresponds to.

string
short_code

Dedicated short code that received the message. Present when your account has a dedicated short code assigned.

string
Examples

Reply received on shared short code

{
  "source_addr": "5218112345678",
  "message": "Hola, quiero más información",
  "sms_id": "MT-9f3a1b7c2d"
}

Responses

Section titled “Responses”

200

Section titled “200”

Your server must return HTTP 200 to acknowledge receipt. Any other status code will trigger a retry from contacta.mx.