The life of a message
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 reports arrive
Most reports arrive within seconds to a few minutes. Some carriers report late or not at all; a message without a report stays in sent.
Refunds
A failed message is refunded to your balance automatically. You can see each refund in your balance 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. Answer with any 2xx status; otherwise we retry up to 8 times over about two 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.
