Skip to main content

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​

LimitTimePast it
Your webhook answers a turn25 secondsThe subscriber sees a fallback message and the session ends
A session has no turn5 minutesPonitor closes the session and sends a closed notice
Your webhook answers a ping5 secondsThe 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.

Ponitor posts an input turn to your USSD webhook and waits 25 seconds. No answer comes, so the phone shows Service temporarily unavailable, and Ponitor sends your webhook a closed notice with the reason webhook_failed.

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 closed notice with reason: "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.

SubscriberNetworkPonitorYour webhookAfter 5 minutes with no turnShows your menuCancels, or stops answeringPOST type: "closed"200 OK
{
"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"
}
reasonWhat happenedWhen it arrives
subscriber_leftThe subscriber canceled, lost signal or took too longAs soon as Ponitor learns of it. MTN only, and not every time
idleThe session had no turn for 5 minutesWithin a minute of the 5 minutes. This is the usual way you learn that a subscriber left
webhook_failedYour answer was late, unreachable or invalid, and the subscriber saw the fallback messageRight after the failed turn

How the notice works:

  • Return any 2xx status. 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​