Skip to main content

Calling your server from an app

An app built in Ponitor can call your own API mid-session. You shape the request; Ponitor sends exactly that and reads the reply. Your API doesn't need to know anything about Ponitor.

Three blocks make requests this way:

  • Webhook, under Integrations in the Blocks panel, calls one of your webhooks and lets later screens read the reply.
  • PIN sends the PIN the caller typed to your API to check it.
  • Dynamic Menu can ask your API for the list it shows, like the caller's groups.

Webhooks​

Every request goes through one of your webhooks, under Developers › Webhooks. The webhook holds the address and how Ponitor authenticates. A block then calls a path under it, like /v1/groups/join, and you change the address or key in one place.

Every request is signed with the webhook's secret: X-Webhook-Signature and X-Webhook-Signature-V2, checked the same way as a webhook event. If your server also checks its own key or token, add Authentication to the webhook:

AuthenticationWhat Ponitor adds
HeaderA header you name, like X-Api-Key, with your key.
BearerAuthorization: Bearer … with your token.
BasicAuthorization: Basic … with your username and password.

Check X-Webhook-Signature-V2: it covers the method, path and query as well as the body, so a copied request can't be sent again to another path. The older X-Webhook-Signature covers only the timestamp and body, which for a GET is just the timestamp. See Signature V2 for how to check it.

Turn away a request more than 5 minutes old, and don't log request headers, or leave out the signatures and Authorization when you do.

Keys are stored encrypted and never shown again, in the dashboard or in an app.

A webhook doesn't need any events ticked: one with none is only called by your apps. The method is set on each block; events always go as POST.

A block's request never turns a webhook off. If it fails, the block takes its Failed way out. Only missed events turn a webhook off, and a webhook that's off still answers your apps.

You can't delete a webhook an app uses.

Shaping the request​

PartNotes
MethodGET, POST, PUT, PATCH or DELETE. A Dynamic Menu always uses GET.
Path or addressVariables are URL-encoded as they're filled in: /v1/groups/{{group.id}}. A value can't add a / or step out of the path with ...
QueryName and value pairs, added as ?name=value.
BodyJSON, for every method but GET.
Example replyA sample of what your API answers. See Example reply.

In the body, a variable inside quotes is sent as text and escaped for you. A variable without quotes is sent as it is, so it must be a number, true, false, a list or an object:

{ "code": "{{code}}", "amount": {{amount}}, "phone": "{{phone}}" }

An empty variable without quotes is sent as null. If a value can't go where you put it, like a name where a number belongs, nothing is sent and the block takes Rejected.

Ponitor adds Accept: application/json, Content-Type: application/json when there's a body, the webhook's signature and its authentication. A write also carries an Idempotency-Key, the same if the network sends the turn twice.

Use Ponitor's format fills in a starter body and example reply. Nothing depends on it; change it to fit your API.

Reading the reply​

Each Webhook block has a ref, made from its name: a block named Join group gets join_group. Later blocks read its reply and HTTP status like this:

You joined {{join_group.reply.group.name}}.
Status: {{join_group.status}}

The ref follows the block's name until you change it by hand. Changing a ref rewrites every place it's used. Two blocks can't share a ref, and a ref can't be one Ponitor uses itself, like phone or contact.

Ponitor keeps only the reply fields the app reads. The rest isn't saved with the session.

Ways out​

Way outWhen
SuccessA 2xx reply.
RejectedA 4xx reply, or a request that couldn't be built from its values (nothing was sent).
FailedThe request never reached your API: a bad address, a refused connection or a failed TLS handshake. For a GET, also a 5xx or no reply in 5 seconds.
No AnswerOnly for writes (every method but GET). The request was sent but the reply was a 5xx or never came, so it may have gone through. If you leave it empty, the block takes Failed.

Ponitor never follows redirects and never sends a write twice. Each write carries an Idempotency-Key header, one per session and visit to the block, so your API can tell a request it has already handled. Use No Answer to tell the caller you're checking, then confirm by SMS.

PIN checks​

A PIN block's request must hold {{pin}}, in the path, query or body. {{pin}} exists only in that request: other blocks can't use it, and Ponitor keeps no copy.

ReplyMeans
2xxThe PIN is right.
4xxThe PIN is wrong. It counts against the block's tries.
Anything elseIt couldn't be checked. The caller is asked again and the try isn't counted.

Tries are counted per caller for the day (UTC), so hanging up and dialing again doesn't reset them. A caller who has used them all goes straight to the block's locked path until the next day. The caller's phone hides the PIN, and the session's history shows it as [redacted]. Keep it out of your own logs too.

Dynamic Menu lists​

A Dynamic Menu set to A webhook makes a GET as the caller reaches it. List Field names the reply field that holds the list, like groups or data.groups. Each option's words come from the item: {{item.name}}. If the request fails or the list is empty, the caller goes to Empty List.

Example reply​

The example reply does three jobs:

  • Its fields are offered as variables, like {{join_group.reply.group.name}}.
  • The Test tab uses it when a write isn't sent (see below).
  • Template previews use it, so they show a believable screen.

Testing​

Send test request, under a block's request, sends it once to your server with values you type for its variables. It shows the status, how long it took and the reply. Use as example reply copies the reply into the block. A write, like a POST, goes for real, so the editor says which server it goes to before you send.

In the editor's Test tab:

  • A GET goes to your server, since reading doesn't change anything.
  • A write isn't sent. The Test tab shows what would have gone, with the PIN masked, and carries on as if your example reply came back.

To try a whole app against a staging server, use Test mode: its webhooks are separate from Live's, so point them at staging there.

Next steps​

  • Read the USSD webhook reference to answer a whole code from your server, or to take over a session with Hand Over.