Docs menuTypeform guide

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.

  1. Make a program (dashboard or POST /programs) with the budget, the amount and per_recipient={"lifetime": 1} if each person is paid once.
  2. 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.
  3. Add a question for the respondent's mobile number to the form (and their meter, if you pay ZESA).

In Typeform

  1. Add a phone number question (or pass the number in as a hidden field if you already know it).
  2. 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.
  3. Each post carries form_response.token, unique per response. That is the completion_id.

The relay

relay.py (Flask)
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.