Timing and timeouts
Your webhook has 25 seconds to answer each screen. This page covers that limit, what to do when a turn needs longer, and what happens when a session goes quiet.
The limits
| Limit | Time | Past it |
|---|---|---|
| Your webhook answers a turn | 25 seconds | The subscriber sees a fallback message and the session ends |
| A session has no turn | 5 minutes | Ponitor closes the session and sends a closed notice |
Your webhook answers a ping | 5 seconds | The webhook isn't saved or turned back on |
Answer within 25 seconds
Ponitor calls your webhook once per turn and waits up to 25 seconds. It doesn't retry.
If your answer is slow, unreachable or invalid:
- The subscriber sees "Service temporarily unavailable. Please try again shortly." and the session ends.
- The turn shows as failed under USSD › Sessions, with the reason.
- It counts as a failed delivery. Ponitor turns off a webhook that fails 5 deliveries in a row. One good answer sets the count back to 0.
- If the first turn of a session fails, the session isn't charged. If a later turn fails, it is.
- Ponitor sends your webhook a
closednotice withreason: "webhook_failed".
Answer as fast as you can. The subscriber watches a waiting screen until you do, and most give up long before 25 seconds. Aim for under 10 seconds.
When a turn needs longer
Some work takes longer than a subscriber will wait, such as a payment that another system must confirm. Start the work, then answer straight away. Don't wait for the result. There are two ways to do it.
Show a holding screen. Return continue with one option. When the subscriber presses it, return the result if it's ready, or the same screen again.
{
"action": "continue",
"screen": "We're checking your balance.",
"options": [{ "label": "See my balance" }]
}
Finish by SMS. Return end, and send the result with the SMS API when it's ready.
{
"action": "end",
"screen": "We're processing your payment. You'll get an SMS shortly."
}
When the subscriber stops answering
A subscriber can cancel, lose signal or take too long. The session closes on their phone, and no further turn reaches your webhook.
- Orange: a subscriber who dials back straight away returns to the screen they were on. Your webhook isn't called for that screen. The next call you get is their answer to it.
- Both networks: Ponitor closes the session after 5 minutes with no turn. On MTN it can close sooner.
Keep each screen short, so the subscriber can read it and answer in a few seconds.
When a session closes without you
A session normally closes when your webhook returns end. When it closes any other way, Ponitor sends your webhook one closed notice, so you can release what the session was holding.
{
"sessionId": "a3f1c9e2-7b44-4e91-9c3a-1d8f0b2e6c77",
"msisdn": "231770000000",
"serviceCode": "*123#",
"carrier": "mtn",
"type": "closed",
"timestamp": "2026-09-14T19:31:40.118Z",
"input": null,
"reason": "subscriber_left"
}
reason | What happened | When it arrives |
|---|---|---|
subscriber_left | The subscriber canceled, lost signal or took too long | As soon as Ponitor learns of it. MTN only, and not every time |
idle | The session had no turn for 5 minutes | Within a minute of the 5 minutes. This is the usual way you learn that a subscriber left |
webhook_failed | Your answer was late, unreachable or invalid, and the subscriber saw the fallback message | Right after the failed turn |
How the notice works:
- Return any
2xxstatus. Ponitor ignores the body, because there is no screen left to show. - Ponitor sends it once and waits up to 3 seconds. It doesn't retry.
- A failed notice doesn't count toward the 5 failures that turn a webhook off.
- It isn't charged, and it doesn't show as a turn under USSD › Sessions.
- It is signed like a turn. Verify it the same way.
- Ponitor doesn't send it when your webhook returned
end, or when your webhook is turned off.
Don't rely on the notice alone:
- Don't wait for it to finish a transaction. Do the work on the turn where the subscriber confirms.
- Still clear your own session state after 6 minutes without a turn. A notice can be lost if your server is down when it is sent.
Next steps
- See the USSD webhook reference for the request, the response and what makes a response invalid.
- Follow one session turn by turn in A session, step by step.