Skip to content

Getting Started

Webhooks

Webhooks can be utilized to get notifications of incoming SMS messages.

Follow these steps to set up webhooks:

  1. Set up your own HTTP server with a valid SSL certificate to receive webhooks. For testing purposes, webhook.site can be useful.
  2. Register your webhook with an API request:

    curl -X POST -u <username>:<password> \
      -H "Content-Type: application/json" \
      -d '{ "id": "unique-id", "url": "https://webhook.site/<your-uuid>", "event": "sms:received" }' \
      http://<device_local_ip>:8080/webhooks
    
  3. Send an SMS to the device.

  4. The application will dispatch POST request to the specified URL with a payload such as:

    {
      "deviceId": "ffffffffceb0b1db0000018e937c815b",
      "event": "sms:received",
      "id": "Ey6ECgOkVVFjz3CL48B8C",
      "payload": {
        "message": "Android is always a sweet treat!",
        "phoneNumber": "6505551212",
        "receivedAt": "2024-06-22T15:46:11.000+07:00"
      },
      "webhookId": "LreFUt-Z3sSq0JufY9uWB"
    }
    
  5. To deregister a webhook, execute a curl request using the following pattern:

    curl -X DELETE -u <username>:<password> \
      http://<device_local_ip>:8080/webhooks/unique-id
    

Note: Webhooks are transmitted directly from the device; therefore, the device must have an outgoing internet connection. As the requests originate from the device, incoming messages remain inaccessible to us.

For more information, see Features: Webhooks