Events

Webhooks

Add your server URL in Webhooks and choose the events. GetSMS sends a JSON POST request for each event.

Without a list of numbers, the webhook receives events from all the numbers that send for you, including GetSMS shared numbers. This is the recommended setting.

Events

Event	When
`message.phone.sending`	The phone starts sending.
`message.phone.sent`	The SMS is handed off to the network.
`message.phone.delivered`	The recipient received the SMS.
`message.send.failed`	The send failed.
`message.send.expired`	The SMS could not go out in time.
`message.phone.received`	A recipient replied to you.

Format

The body follows the CloudEvents format. The X-Event-Type header contains the event name.

{
  "specversion": "1.0",
  "id": "5c1a3bba-09cc-41a6-a4bb-c8f4872dce4d",
  "type": "message.phone.received",
  "time": "2026-11-10T09:42:11Z",
  "datacontenttype": "application/json",
  "data": {
    "message_id": "8f9c71b8-b84e-4417-8408-a62274f65a08",
    "owner": "+212661234501",
    "contact": "+212612345678",
    "content": "Yes, thanks",
    "timestamp": "2026-11-10T09:42:09Z"
  }
}

Verify the signature

If you set a signing key, each request carries an Authorization: Bearer <token> header. It is a JWT signed with HS256 using your key, valid for 10 minutes, whose audience is your webhook URL. Reject any request with an invalid token.

Node.js (Express)
Python (Flask)

import jwt from "jsonwebtoken";

app.post("/hooks/sms", express.json(), (req, res) => {
  const token = (req.get("Authorization") || "").replace("Bearer ", "");
  try {
    jwt.verify(token, process.env.GETSMS_SIGNING_KEY, {
      algorithms: ["HS256"],
      audience: "https://atlas-shop.ma/hooks/sms",
    });
  } catch {
    return res.sendStatus(401);
  }

  if (req.body.type === "message.phone.received") {
    const { contact, content } = req.body.data;
    // e.g. confirm the order if content is "1" or "OUI"
  }
  res.sendStatus(200);
});

import os, jwt
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/hooks/sms")
def sms_hook():
    token = request.headers.get("Authorization", "").removeprefix("Bearer ")
    try:
        jwt.decode(token, os.environ["GETSMS_SIGNING_KEY"], algorithms=["HS256"],
                   audience="https://atlas-shop.ma/hooks/sms")
    except jwt.InvalidTokenError:
        abort(401)

    event = request.get_json()
    if event["type"] == "message.phone.received":
        contact, content = event["data"]["contact"], event["data"]["content"]
    return "", 200