Exports & Integrations

    Webhooks: Send Responses to Your System

    Push signed JSON payloads to your API when responses are submitted or approved.

    Last updated: Jul 3, 2026

    Webhooks: Send Responses to Your System

    Webhooks push a signed JSON payload to your API the moment something happens — so approved account-opening forms, registrations, or applications flow straight into your core system with no re-keying.

    Setting Up

    1. Open your form → Settings → Integrations → Send responses to your system
    2. Switch it on — a signing secret is generated automatically
    3. Enter your endpoint URL (must be https:// and publicly reachable)
    4. Choose when to send:
      • A response is approved — fires after your review/approval workflow completes, with all official-use fields included. Recommended for downstream systems.
      • A response is submitted — fires immediately on every new submission, before any review.
    5. Click Send a test delivery to confirm your endpoint responds, then save the form

    Only organization admins can configure webhooks.

    The Payload

    {
      "event": "response.approved",
      "form": { "id": "…", "title": "Account Opening" },
      "response": {
        "id": "…",
        "submitted_at": "2026-07-03T10:30:00Z",
        "respondent_name": "…",
        "respondent_email": "…"
      },
      "answers": { "Full name": "…", "National ID": "…" },
      "answers_by_id": { "field-uuid": "…" },
      "official_answers": { "Reviewed by": "…", "Account number": "…" },
      "review": {
        "status": "approved",
        "reviewed_by": "…", "reviewed_at": "…",
        "approved_by": "…", "approved_at": "…"
      },
      "sent_at": "…"
    }
    

    answers is keyed by field label for readability; answers_by_id is keyed by stable field IDs for machine mapping.

    Verifying Deliveries (do this!)

    Every request carries three headers:

    • X-Jawaab-Event — the event name
    • X-Idempotency-Key — stays identical across retries of the same delivery, so you can safely drop duplicates
    • X-Jawaab-Signature — t=<unix-timestamp>,v1=<hex> where v1 is an HMAC-SHA256 of "<timestamp>.<raw body>" computed with your signing secret

    Recompute the HMAC on your server and compare before trusting a payload. Reject requests whose timestamp is more than a few minutes old to prevent replays.

    Retries & the Delivery Log

    Failed deliveries retry automatically with backoff — after 1 minute, 5 minutes, 30 minutes, 2 hours, and 6 hours — then are marked dead. The Recent deliveries log under the webhook settings shows every attempt with its status code and error, and lets you redeliver any delivery manually. Responses to your endpoint must return a 2xx within 10 seconds.

    Security Notes

    • Endpoints must be https on a public host — private-network and IP-literal URLs are rejected
    • Regenerating the secret invalidates signatures on your side — update your endpoint at the same time
    • Test deliveries contain sample data only, never real responses

    Was this article helpful?