Webhooks and events

@opencoredev/sms-sdk/webhooks: parseSmsWebhook options per provider, the SmsEvent union, keyword helpers, and signature verify helpers.

import { parseSmsWebhook, type SmsEvent } from "@opencoredev/sms-sdk/webhooks";

parseSmsWebhook(options)

Reads the request body once, verifies the provider’s signature, and returns a normalized SmsEvent. No field is interpreted before verification succeeds.

import { parseSmsWebhook } from "@opencoredev/sms-sdk/webhooks";

export async function POST(request: Request): Promise<Response> {
  const event = await parseSmsWebhook({
    provider: "twilio",
    request,
    publicUrl: "https://example.com/webhooks/sms/twilio",
    credentials: { authToken: process.env.TWILIO_AUTH_TOKEN ?? "" },
  });
  console.log(event.type, event.dedupeKey);
  return new Response(null, { status: 200 });
}

Guides: Receive webhooks, Webhook security.

Parameters

Options are discriminated by provider. Every variant accepts the common options.

Per-provider options:

publicUrl is the exact URL configured with the provider. If it has no query string, the request’s query string is appended. Without publicUrl, trustProxy: true builds the URL from X-Forwarded-Proto and X-Forwarded-Host. Otherwise request.url is used and forwarded headers are ignored. See Webhook security.

Returns

Promise<SmsEvent>.

Throws

• WebhookSignatureError (code: "webhook_signature") when the request is not authentic. reason is missing_signature, invalid_signature, stale_timestamp, body_hash_mismatch, malformed_signature, or invalid_credentials. Respond 401 or 403.
• WebhookPayloadError (code: "webhook_payload") when an authentic payload lacks required fields.

SmsEvent

Every event has these fields.

message.received

{ type: "message.received"; providerId: string; from: string; to: string; body: string; mediaUrls: readonly string[] }

An inbound message. from is the sender and to is your number. Vonage and Sinch numbers that arrive without + are normalized to E.164. Media comes from Twilio, Telnyx, Plivo, and Bandwidth; mediaUrls is always empty for Vonage and Sinch. Media URLs point at provider storage, may expire, and may need provider credentials to fetch.

SMS SDK never replies on its own and does not store conversations. Twilio also lets you reply by returning TwiML. SMS SDK does not build TwiML; to send no reply, return <Response></Response> with Content-Type: text/xml. See Receive webhooks.

Status events

{
  type: "message.queued" | "message.sent" | "message.delivered" | "message.undelivered" | "message.filtered";
  providerId: string;
  providerStatus: string; // the provider's own status value
  errorCode?: string;
  from?: string;
  to?: string;
}

A status update for an outbound message. MessageStatusType is the union of these five types. The mapping per provider is in Status mapping.

Opt-out and help events

{
  type: "recipient.opted_out" | "recipient.opted_in" | "recipient.help";
  providerId: string;
  from: string;
  to: string;
  body: string; // the original inbound text
  source: "provider" | "keyword";
  keyword: string;
}

source: "provider" comes from Twilio’s OptOutType. source: "keyword" comes from whole-message keyword matching. recipient.opted_in comes only from Twilio OptOutType=START. See STOP, HELP, and opt-outs.

unrecognized

{ type: "unrecognized"; providerEventType: string }

A verified event SMS SDK does not map, such as Twilio read or a new Telnyx event type. Inspect raw. A provider’s new statuses arrive here instead of breaking your handler.

Where to point webhooks

Status updates go to the status URL, set per message with webhookUrl or once in the provider’s console:

Texts to your number go to the URL set on the number or its group. A per-message webhookUrl only affects status events.

Status mapping

message.filtered means a carrier or the provider blocked the message as spam or for its content. It needs one of the error codes above; any other failure stays message.undelivered. Telnyx status events come from its message.sent and message.finalized webhooks.

delivered means the carrier reported delivery to the handset, and not every carrier does. Some routes stop at sent, and Telnyx reports delivery_unconfirmed when there is no receipt. Treat message.sent with nothing after it as probably delivered. SMS SDK does not poll for status, so if a webhook never arrives, look the message up with the provider.

Duplicates and ordering

Dedupe keys

dedupeKey stays the same each time the provider delivers the same event, and starts with the provider name, so keys from two providers never collide.

Storing keys

• Insert keys atomically, such as INSERT ... ON CONFLICT DO NOTHING that returns whether a row was inserted. Reading first and inserting second lets two parallel deliveries both pass.
• Keep keys at least as long as the provider retries, typically a day or more.
• Answer repeats with a 2xx, because an error makes the provider retry again. Respond fast and do slow work in a background job, since a timeout also causes a retry.
• With several servers or serverless functions, keep keys in a shared database. See Share idempotency across servers.

Ordering

Providers send events in parallel, so message.sent can arrive after message.delivered. Never let a late event move a message backward. Rank the statuses and keep the highest:

import type { MessageStatusType } from "@opencoredev/sms-sdk/webhooks";

const rank: Record<MessageStatusType, number> = {
  "message.queued": 0,
  "message.sent": 1,
  "message.delivered": 2,
  "message.undelivered": 2,
  "message.filtered": 2,
};

export function nextStatus(current: MessageStatusType | undefined, incoming: MessageStatusType): MessageStatusType {
  if (current === undefined) return incoming;
  return rank[incoming] >= rank[current] ? incoming : current;
}

console.log(nextStatus("message.delivered", "message.sent")); // "message.delivered"

The final states share a rank, so the last one to arrive wins. Providers rarely send two different final states; when they do, occurredAt, if present, says which came later.

A status webhook can also arrive before you have saved the send() result. Upsert the status row by providerId, or hold unknown IDs briefly and apply them once the send result is saved.

Keyword helpers

detectKeyword(body)

Matches a whole message against the keyword lists, ignoring case, surrounding whitespace, and trailing ., !, or ?.

import { detectKeyword } from "@opencoredev/sms-sdk/webhooks";

console.log(detectKeyword("Stop!")); // { kind: "opted_out", keyword: "STOP" }
console.log(detectKeyword("help")); // { kind: "help", keyword: "HELP" }
console.log(detectKeyword("Please stop texting me")); // undefined

Returns KeywordMatch | undefined, where KeywordMatch is { kind: "opted_out" | "help"; keyword: string }.

OPT_OUT_KEYWORDS and HELP_KEYWORDS

• OPT_OUT_KEYWORDS: ["STOP", "STOPALL", "UNSUBSCRIBE", "CANCEL", "END", "QUIT"]
• HELP_KEYWORDS: ["HELP", "INFO"]

Per-provider parsers

parseTwilioWebhook, parseTelnyxWebhook, parsePlivoWebhook, parseVonageWebhook, parseBandwidthWebhook, and parseSinchWebhook take the same options as parseSmsWebhook without provider, with option types TwilioWebhookOptions, TelnyxWebhookOptions, PlivoWebhookOptions, VonageWebhookOptions, BandwidthWebhookOptions, and SinchWebhookOptions.

Verify helpers

These check a signature without parsing, for example in middleware.

verifyTwilioSignature({ authToken, url, params, signature })

Returns Promise<boolean>. params is a list of [name, value] pairs from the form body, empty for JSON bodies and GET requests. Tries the URL with and without the default port.

computeTwilioSignature({ authToken, url, params }) returns the expected X-Twilio-Signature as Promise<string>.

verifyTelnyxSignature({ publicKey, rawBody, signature, timestamp, toleranceSec?, now? })

Returns Promise<WebhookVerification>, either { valid: true } or { valid: false, reason }. signature and timestamp are the telnyx-signature-ed25519 and telnyx-timestamp header values, or null. now is epoch ms. TELNYX_DEFAULT_TOLERANCE_SEC is 300.

verifyPlivoSignatureV2({ authToken, url, nonce, signature })

Returns Promise<boolean>. url may include a query string, which is removed before signing. computePlivoSignatureV2({ authToken, url, nonce }) returns the expected signature.

verifyVonageSignature({ signatureSecret, authorization, rawBody, toleranceSec?, now? })

Returns Promise<WebhookVerification>. authorization is the Authorization header value, or null. VONAGE_DEFAULT_TOLERANCE_SEC is 300.

import { verifyTelnyxSignature } from "@opencoredev/sms-sdk/webhooks";

export async function isAuthentic(request: Request): Promise<boolean> {
  const result = await verifyTelnyxSignature({
    publicKey: process.env.TELNYX_PUBLIC_KEY ?? "",
    rawBody: await request.clone().text(),
    signature: request.headers.get("telnyx-signature-ed25519"),
    timestamp: request.headers.get("telnyx-timestamp"),
  });
  return result.valid;
}

Types

Exported from @opencoredev/sms-sdk/webhooks: ParseSmsWebhookOptions, SmsEvent, SmsEventBase, MessageReceivedEvent, MessageStatusEvent, MessageStatusType, RecipientKeywordEvent, UnrecognizedEvent, WebhookProvider, KeywordMatch, WebhookCommonOptions, SignedUrlOptions, WebhookVerification, the six per-provider option types, BandwidthWebhookCredentials, SinchWebhookCredentials, and WebhookFailureReason.