Build
Typeform guide
A signed Typeform webhook, checked, then rewarded.
How it fits together
Typeform can post each submission to a URL, but it cannot sign a request the way Jusa's completions endpoint
wants or hold a secret key safely. So a small relay of yours sits between them: Typeform posts to it, it checks the
post really came from your form, and it calls POST /rewards, keyed on the submission so each is paid
once, forever.
- Make a program (dashboard or
POST /programs) with the budget, the amount andper_recipient={"lifetime": 1}if each person is paid once. - Make a restricted key with only
rewards:write, and give it to the relay. If it ever leaks, it can reward from that program's budget and do nothing else. - Add a question for the respondent's mobile number to the form (and their meter, if you pay ZESA).
In Typeform
- Add a phone number question (or pass the number in as a hidden field if you already know it).
- Open Connect → Webhooks, add your relay's URL and set a secret. Typeform then
signs each post with
Typeform-Signature: sha256=<base64 HMAC-SHA256 of the body>, which the relay checks. - Each post carries
form_response.token, unique per response. That is thecompletion_id.
The relay
import base64
import hashlib
import hmac
import logging
import os
from http import HTTPStatus
from flask import Flask, abort, request
import jusa
logger = logging.getLogger(__name__)
jusa.api_key = os.environ["JUSA_REWARDS_KEY"] # jusa_rk_… with rewards:write only
SURVEY_PROGRAM_ID = os.environ["JUSA_PROGRAM"]
# Worth Typeform posting again: nothing was charged, and the same keys never pay twice.
TRY_AGAIN_LATER = (jusa.InsufficientCreditError, jusa.RateLimitError, jusa.ProviderUnavailableError,
jusa.APIConnectionError, jusa.APIError)
app = Flask(__name__)
@app.post("/typeform")
def typeform():
digest = hmac.new(os.environ["TYPEFORM_SECRET"].encode(), request.get_data(), hashlib.sha256).digest()
expected_signature = "sha256=" + base64.b64encode(digest).decode()
if not hmac.compare_digest(expected_signature, request.headers.get("Typeform-Signature", "")):
abort(HTTPStatus.FORBIDDEN)
form_response = request.get_json()["form_response"]
response_token = form_response["token"] # unique per response
phone = next(answer["phone_number"] for answer in form_response["answers"] if answer["type"] == "phone_number")
try:
jusa.Reward.create(
program=SURVEY_PROGRAM_ID,
recipient={"phone": phone},
completion_id=response_token,
idempotency_key=f"typeform-{response_token}",
)
except TRY_AGAIN_LATER as temporary_error:
logger.warning("Typeform will post %s again: %s [%s]", response_token, temporary_error.code,
temporary_error.request_id)
return "", HTTPStatus.SERVICE_UNAVAILABLE
except jusa.JusaError as refusal:
# A cap or a blocked number is final for this response: answer 2xx so Typeform stops.
logger.warning("Jusa refused %s: %s [%s]", response_token, refusal.code, refusal.request_id)
return "", HTTPStatus.OK
Typeform sends numbers in international form (+2637…); Jusa takes any Zimbabwean format. Test with a
test key first, then swap it.