How do I receive SMS by webhook?

Open the account menu, choose “API Keys”, go to the “Webhooks” tab and add a public HTTPS address of your server. SMSZ then sends each incoming SMS to that address as soon as it arrives, so you no longer need to poll the API.

Updated November 18, 2026

A webhook is an address on your server that SMSZ calls when something happens on your account. Each message reaches you as it arrives, signed, with the same data the API returns. You can add an endpoint without an API key. To test it or change its events through the API, you need a key: see how to create an API key.

Set up the endpoint

  1. Prepare a URL on your server that accepts POST requests. It must be a public HTTPS address. Local addresses such as localhost are refused.
  2. Sign in, open the account menu, choose “API Keys” and open the “Webhooks” tab.
  3. Paste the URL into “Deliver events to” and press “Add”.
  4. Copy the signing secret that appears. It starts with whsec_ and is shown only once. Store it on your server, then press “I have saved it”.

An endpoint added here receives all events. You can narrow the list later through the API. One account can have up to 10 endpoints.

Which events carry the SMS

Each delivery is a JSON event with a type and a data object. Incoming SMS come as activation.message.received for one-time numbers and rental.message.received for rented numbers. The data object holds the number and its messages: text is the full SMS, and code is the code when one could be read. Other events, such as balance changes, come to the same URL, so skip the types you do not use.

Check the signature

Every delivery has an SMSZ-Signature header with a timestamp t and a signature v1. Compute HMAC-SHA256 of the timestamp, a dot and the raw request body, with your signing secret as the key, and compare the result with v1. Check the raw body before you parse the JSON, and reject old timestamps so that a captured request cannot be sent again. The webhooks guide has ready code in JavaScript and Python.

Answer fast and expect retries

  • Reply with any 2xx status within 10 seconds. Do the slow work after you reply.
  • If your server does not answer with 2xx, SMSZ tries again, up to 8 times over a little more than 24 hours. Redirects are not followed.
  • The same event can arrive more than once, and the order is not guaranteed. Skip events whose id you have already handled.
  • After 20 failures in a row the endpoint is switched off and shows “disabled” in the Webhooks tab. Fix your server, then press “Re-enable”.

Test it

The API can send a test event: a real, signed delivery with clearly fake data, and it reports what your server answered. The delivery log in the API shows every attempt and your response code. The Webhooks tab shows the last successful delivery and the number of failures. No public server? Read the same events from the event list in the API, which keeps them for 30 days.

Lost the signing secret? Delete the endpoint and add it again to get a new secret. Deliveries still queued for the old endpoint are dropped.

Still stuck? Write to us

Email [email protected] or use the contact page. We usually reply within 24 hours. To get it solved in one reply, include: