Can I receive webhook notifications for incoming SMS using SMSVerifier API instead of polling?

SMSVerifier API supports webhook notifications for incoming SMS, allowing you to receive OTP codes instantly without the need to poll for updates.

Webhook Support Overview

SMSVerifier offers webhook notifications as a modern alternative to the traditional polling method for receiving SMS OTP codes. Instead of repeatedly querying the API for new messages, your server receives instant HTTP callbacks whenever an SMS arrives on a rented virtual number.

This feature is ideal for developers building real-time verification flows, automated sign-up pipelines, or multi-factor authentication systems that depend on prompt OTP retrieval.

Setting Up Webhooks with SMSVerifier

To configure webhook notifications for incoming SMS through SMSVerifier, follow these steps:

• Step 1 — Define your webhook endpoint Create a publicly accessible HTTPS endpoint on your server that can accept POST requests containing JSON payloads.
• Step 2 — Configure webhook URL in your account Set your webhook URL in the SMSVerifier dashboard under API settings or specify it per request when ordering a number.
• Step 3 — Purchase a virtual number with webhook enabled When requesting a number via API, include the webhook parameter to activate callback notifications.
• Step 4 — Handle incoming webhook requests Parse the JSON payload in your server logic to extract OTP codes and related data instantly when SMS is received.

Webhook Payload Details

SMSVerifier sends a JSON payload to your webhook URL each time an SMS arrives on your rented number. The payload typically includes:

• phone_number: The virtual phone number receiving the SMS.
• service: The target service for which the OTP was sent (e.g., WhatsApp, Google).
• sms_text: The full text of the received SMS containing the OTP.
• timestamp: The exact time the SMS was received in ISO 8601 format.
• request_id: A unique identifier to correlate the webhook with your API request.

Example webhook payload:

{
  "phone_number": "+1234567890",
  "service": "WhatsApp",
  "sms_text": "Your verification code is 123456",
  "timestamp": "2024-06-01T12:34:56Z",
  "request_id": "abc123xyz"
}

Limitations and Compatibility

While webhooks are broadly supported across SMSVerifier's platform, there are some important limitations and compatibility notes:

• Not all upstream providers support webhook callbacks; in such cases, polling remains necessary.
• Some countries or services may have restrictions on real-time webhook delivery due to carrier limitations.
• If you rely on webhooks exclusively, verify support for your target service (e.g., Telegram, Instagram) and country.

For details on service availability, see our supported services list and country-specific pages such as USA virtual numbers.

Handling Webhook Failures

Webhook delivery depends on your endpoint's availability. If your server is down or slow to respond, SMSVerifier implements retry mechanisms but there are limits:

• Retries occur at exponentially increasing intervals for up to several attempts.
• If delivery consistently fails, webhooks may be disabled temporarily, and you will need to fallback to polling to ensure no SMS is missed.

Also, respond with HTTP status code 200 quickly to acknowledge receipt and prevent unnecessary retries.

Security Considerations for Webhooks

Security is critical when receiving OTP codes via webhooks. SMSVerifier provides several measures to secure webhook communication:

• HMAC signatures: Each webhook request includes an HMAC signature header that you can use to verify authenticity.
• HTTPS: Use SSL/TLS encryption to protect data in transit.
• IP whitelisting: Optionally restrict access to your webhook endpoint to SMSVerifier IP ranges.

Refer to our API documentation for detailed instructions on signature validation and recommended security best practices.

API Documentation and Resources

To get started with webhook integration, consult the official SMSVerifier API documentation which covers:

• Webhook setup parameters during number purchase
• Complete webhook payload schemas
• Signature verification examples in various programming languages
• Error handling and retry policies

Explore the API docs at /api/docs and try live examples at /api-playground.