Delivery status webhooks

Learn whether an accepted message was delivered: configure status callbacks and map each provider's statuses to SmsEvent types.

A successful send() means the provider accepted the message. It does not mean the phone received it. The result’s handoff is always "accepted", and delivery holds the status the provider reported at that moment, usually queued. Delivery arrives later as a status webhook. parseSmsWebhook() turns it into a message.* event that you match to the send by providerId.

1. Point the provider at your endpoint

Set the status URL per message or in the provider’s console:

Per message:

import { sms } from "./sms";

const result = await sms.send({
  to: "+14155550123",
  body: "Your order has shipped.",
  webhookUrl: "https://example.com/webhooks/sms/twilio",
});

Save result.providerId with the message. Status events carry the same ID.

2. Parse the status event

import { parseSmsWebhook, WebhookSignatureError } from "@opencoredev/sms-sdk/webhooks";
import { db } from "./db";

export async function POST(request: Request): Promise<Response> {
  try {
    const event = await parseSmsWebhook({
      provider: "twilio",
      request,
      publicUrl: "https://example.com/webhooks/sms/twilio",
      credentials: { authToken: process.env.TWILIO_AUTH_TOKEN ?? "" },
    });

    if (
      event.type === "message.queued" ||
      event.type === "message.sent" ||
      event.type === "message.delivered" ||
      event.type === "message.undelivered" ||
      event.type === "message.filtered"
    ) {
      await db.messages.updateStatus(event.providerId, event.type, event.errorCode);
    }
    return new Response(null, { status: 200 });
  } catch (error) {
    if (error instanceof WebhookSignatureError) {
      return new Response("Invalid signature", { status: 401 });
    }
    throw error;
  }
}

Each status event has providerId and providerStatus, the provider’s own status word such as undelivered. It also has errorCode, from, and to when the provider sent them. Twilio and Plivo sign the URL they called, which is why the example passes publicUrl. See Webhook security.

Status mapping

Telnyx status events come from its message.sent and message.finalized webhooks.

Any other status, such as Twilio read or canceled or Plivo read, becomes { type: "unrecognized", providerEventType } instead of throwing. A provider adding a status does not break your handler.

message.filtered requires an error code that marks the message as spam or blocked content. A plain failure stays message.undelivered. Plivo has no documented filter signal, so its failures are always message.undelivered.

What “delivered” means

delivered means the carrier reported delivery to the handset. Not every carrier reports it. Some routes stop at sent, and Telnyx reports delivery_unconfirmed, mapped to message.sent, when the carrier gives no receipt. Treat message.sent with no later event as probably delivered but unconfirmed.

Limitations

• Status webhooks repeat and arrive out of order. See Duplicates and ordering.
• Vonage with Basic auth (apiKey and apiSecret) does not send status webhooks. Use JWT auth.
• When you switch providers, configure status URLs and webhook credentials on the new one too.
• SMS SDK does not poll for status. If a webhook never arrives, look the message up with the provider.

Next steps

• Inbound SMS
• Webhook events reference