Blog

Order confirmation calls by API: a developer checklist

· · 5 min read · Md. Romizul Islam

Connecting confirmation calls to a store takes about an afternoon. Making sure it still works on a busy Friday, with the courier pickup at four and a flaky network, comes down to a few decisions you make up front. This is the list we give developers before they start.

The integration guide has the endpoint details. This post covers the overall design, and what a good confirmation call sounds like covers what the customer hears.

Your system sends a call request; the agent calls, tries again if nobody answers, and sends the result to your webhookOne request per order, one signed result per call.

Send the call request when the order is final, not when the cart is created

The call reads the order back to the customer. If the order can still change after the request goes out (a coupon applied late, a quantity edited), the customer hears the wrong order and says no. Send the request from the point in your flow where the order is what the courier will carry.

Make the request idempotent

Order webhooks sometimes fire twice, and workers retry. If one order can produce two call requests, the customer gets two calls and confirms the same order twice, or worse, you end up with a duplicate on your side. Use the order number as the request's identity, so the same order number always means the same call request, however many times it is sent.

Verify the webhook signature, every time

The result comes back to your webhook with a signature. Check the signature before you touch the payload. If your webhook endpoint accepts anything, then one day someone will guess the URL and mark an order confirmed. Read the signing secret once at deploy time, keep it out of logs, and rotate it if it ever leaks.

Treat "confirmed" as the only automatic path

The result carries the outcome and, for anything but a clean confirmation, a reason. Only a confirmed result should move an order to "ready to ship" on its own. Cancelled, changed, wrong number, no answer and abusive all belong in a hold queue for a person. Build the hold queue first. That is where fake and duplicate orders end up, so it is where most of the benefit is.

Keep the address the customer said beside the one you sent

The result includes the address as you sent it, the thana and district the customer gave, and a label line already put together. Store all of it. The original address is what the customer typed. The thana and district they said are what the courier needs. The label line is what you print. Do not overwrite the original, and do not try to merge them into one field.

These are the fields the result carries:

FieldWhat it holds
eventcall.result for a call; account events such as balance.low use the same webhook
order_idYour reference, sent back unchanged
statusconfirmed or hold; only confirmed should ship on its own
reasonWhy a call is on hold, for the person who reviews it
summaryOne line about what was said
address.originalThe address you sent, unchanged
address.thana, address.zillaWhat the customer said on the call
address.fullThe label line, joined for you
attemptWhich try settled it
duration_secondsThe billed length of the call
balance_secondsYour balance after this call

Expect the result late, and reconcile

Most results arrive within minutes. Some take longer: the customer did not answer and the retries are spaced out over hours. Your webhook receiver should be fine with hearing about an order it last saw yesterday. Also run a check about once an hour that asks for the status of any order still waiting. A webhook can be missed even with retries, and the hourly check catches those.

Watch the balance

Minutes are prepaid. The result payload tells you how many seconds are left. When that drops below a day's worth of calls, alert someone. A shop that runs out of balance at three in the afternoon ships unconfirmed orders that evening.

Test on your own phone first

Every account starts with a staging assistant that calls the number you give it. Send it a real order shape with your own phone number, listen to the call, read the webhook payload, and only then point the integration at customers. It takes ten minutes and saves you from most surprises.

Sworborno's API is one endpoint to request a call and one webhook to receive the result, with signed payloads and retries built in. The docs walk through both, and pricing is per second of call time. Sign up and the staging assistant is ready when you log in.

Questions people ask

How do I stop duplicate order confirmation calls from API retries?
Use the order number as the request's identity. Sending the same order number again should refer to the same call request, even when a webhook fires twice or a worker retries.
What should my store do if a call result webhook never arrives?
Run a status check about once an hour for orders still waiting. Results can arrive late because unanswered calls are retried over hours, and reconciliation catches missed webhooks.

Connect confirmation calls to your code

Request a call through one endpoint and receive the result at one webhook, with signed payloads and retries. The API docs cover both sides of the integration.

← All posts