MailSlurp logo

mobile

SMS Webhooks for Inbound Text Message Automation

Forward inbound SMS to your application with MailSlurp phone-number webhooks, then verify message receipt and processing with API evidence.

An SMS webhook sends a new inbound text message from a MailSlurp phone number to your HTTP endpoint. Use it when an application needs to react to replies continuously: update a conversation, advance a verification flow, create a support event, or start an automation.

The original message remains accessible through MailSlurp, so a webhook does not have to be your only source of evidence. You can compare what MailSlurp received with what your application stored when debugging a failed route.

Quick answer

  1. Provision a MailSlurp phone number.
  2. Create a webhook for that phone number and your HTTPS endpoint.
  3. Send an SMS to the number.
  4. Acknowledge the webhook quickly and store the message reference or payload.
  5. Process the message in your application.
  6. Use the SMS API or dashboard to investigate missing or failed work.
// create a webhook for a phone number to have new SMS sent to your server
const webhook = await mailslurp.webhookController.createWebhookForPhoneNumber({
  phoneNumberId: phoneNumber.id,
  createWebhookOptions: {
    eventName: CreateWebhookOptionsEventNameEnum.NEW_SMS,
    url: "https://myserver.com",
    name: "Process SMS",
  },
});

Webhook or wait API?

Situation Use
A test expects one SMS after a known action Wait for SMS
A running service handles every inbound reply SMS webhook
An operator needs to inspect message history Dashboard or SMS retrieval API
A failed webhook needs reconciliation Webhook event plus SMS retrieval API

A Playwright test is usually clearer with a wait call because the trigger and assertion live in one run. A support or routing service is usually clearer with a webhook because the sender can reply at any time.

Build a dependable webhook receiver

Acknowledge receipt before heavy work

Keep the request handler focused on accepting the event and recording enough context to process it safely. Move slow parsing, enrichment, or customer-system updates to a queue or background job.

Keep the MailSlurp message identity

Store the message and phone-number identifiers alongside your own conversation or job ID. When a route fails, those values let you open the original SMS and compare the received body with the application outcome.

Make downstream work safe to repeat

Your HTTP layer and workers may encounter retries or partial failures. Before creating a ticket, updating an order, or sending a response, check whether your application has already handled the same message.

Separate unknown senders from trusted workflows

Use phone-number rulesets where appropriate to allow or block sender numbers or patterns. Still validate every inbound message in your application before it changes account state or triggers a sensitive action.

Example inbound routes

Route a customer reply

Attach a MailSlurp number to the test conversation. When the customer replies, the webhook can add the text to the conversation record and notify the responsible workflow. Retain the MailSlurp message ID so an operator can inspect the source.

Test an event-driven OTP flow

Some systems react to inbound verification messages outside a browser test. Use the webhook to capture the event, then assert that the correct test user advances. For a direct browser-controlled OTP test, the wait API is usually simpler.

Combine email and SMS routing

If customers can respond through either channel, route MailSlurp email and SMS events into a shared application model while preserving the original channel, address or number, message ID, and timestamp. This keeps the customer history readable without flattening away delivery details.

Test the webhook before release

  1. Create or assign a controlled MailSlurp phone number.
  2. Point its webhook to a staging endpoint.
  3. Send a text from a known number.
  4. Confirm your endpoint acknowledges the event.
  5. Assert the application creates exactly one expected result.
  6. Deliberately fail downstream processing and verify recovery does not duplicate that result.
  7. Compare the stored application record with the original SMS in MailSlurp.

Troubleshooting

MailSlurp received the SMS but my application did nothing

Open the original message in the dashboard, then check whether the webhook request reached the endpoint and whether downstream processing failed after receipt. Keeping receipt and processing logs separate makes this distinction visible.

The application created duplicate work

Use the MailSlurp message identifier as part of your application's deduplication check. Treat retries as another attempt to process the same message, not as a new customer reply.

The webhook works in development but not staging

Verify the configured URL, network access, HTTPS termination, and environment-specific secrets. Send a new controlled message after each change so the test has a clear trigger time.

FAQ

What is an SMS webhook?

It is an HTTP notification sent to your application when a MailSlurp phone number receives a text message.

Do I still need the SMS API when I use webhooks?

Keep API access for inspection, testing, and reconciliation. The webhook is the live event path; the SMS API and dashboard help you verify what actually arrived.

Can I use SMS webhooks for OTP tests?

Yes. Webhooks work well for event-driven systems. When one browser test triggers and consumes one OTP, a MailSlurp wait call is often simpler and easier to diagnose.