PortSMS

Delivery reports and webhooks

How SMS delivery results move through queued, sent, delivered and failed, and when they arrive. Automatic refunds, webhooks and the X-PortSMS-Signature check.

Updated 2026-10-13

How a message moves

After you send, each recipient is queued and charged, then handed to a carrier route (sent). The carrier later reports whether the phone received it (delivered) or not (failed).

When delivery results arrive

Most results arrive within seconds to a few minutes. When a carrier sends no result, the message stays in sent.

Refunds

An undelivered (failed) message is refunded to your credit automatically. Each refund is one line in your credit history, with the message id.

Receiving webhooks

Add an https address on the API key page. When a message is delivered or fails, we POST a JSON body with the message id, number, status, price and your ref. Your server answers with a 2xx status. Until a 2xx answer arrives, we send up to 8 attempts including the first, over about 2 hours.

Checking the signature

Every webhook carries X-PortSMS-Signature: t=<time>,v1=<hex>. Compute HMAC-SHA256 of the text t.body with your signing secret and compare it with v1. Refuse requests older than five minutes so an old request cannot be replayed.