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.