Guide to Typeform Webhooks Features and Best Practices

Typeform has become one of the most popular form and survey platforms, known for its conversational, one-question-at-a-time interface that drives higher completion rates. Beyond collecting responses, Typeform's webhook system enables developers to push form submissions to external systems in real-time, powering integrations with CRMs, databases, notification systems, and custom automation workflows.

This guide covers everything you need to know about Typeform webhooks: their features, how to configure them, best practices for production deployments, and the common pain points developers face along with solutions to address them.

What are Typeform webhooks?

Typeform webhooks are HTTP callbacks that deliver form response data to external endpoints whenever a respondent submits a typeform. When a new submission comes in, Typeform immediately sends an HTTP POST request containing the response data as a JSON payload to the URL you configure. This enables real-time integration with CRMs, databases, messaging platforms, and any service that can receive HTTP requests.

Typeform webhooks can be configured in two ways:

• Workspace UI — Configure webhooks directly in the Typeform builder under Connect > Webhooks
• Webhooks API — Programmatically create and manage webhooks via PUT /forms/{form_id}/webhooks/{tag}

Each webhook is scoped to a single form, and a form can have multiple webhooks, all of which fire when a response is received.

Typeform webhook features

Supported event types

Typeform webhooks can be configured to trigger on the following events:

By default, webhooks trigger only on full submissions. You can enable partial response tracking via the API by setting event_types.form_response_partial to true when creating or updating the webhook.

A webhook cannot be configured to trigger only on partial responses. It's either full submissions only, or both partial and full submissions together.

Webhook payload structure

When a respondent submits a typeform, Typeform delivers a JSON payload via HTTP POST. Here's a simplified example showing the top-level structure:

{
  "event_id": "LtWXD3crgy",
  "event_type": "form_response",
  "form_response": {
    "form_id": "lT4Z3j",
    "token": "a3a12ec67a1365927098a606107fac15",
    "response_url": "https://admin.typeform.com/form/lT4Z3j/results?responseId=...",
    "submitted_at": "2025-01-18T18:17:02Z",
    "landed_at": "2025-01-18T18:07:02Z",
    "calculated": { "score": 9 },
    "variables": [
      { "key": "score", "type": "number", "number": 4 }
    ],
    "hidden": { "user_id": "abc123456" },
    "definition": {
      "id": "lT4Z3j",
      "title": "Customer Feedback",
      "fields": [ ... ],
      "endings": [ ... ]
    },
    "answers": [ ... ],
    "ending": {
      "id": "dN5FLyFpCMFo",
      "ref": "01GRC8GR2017M6WW347T86VV39"
    }
  }
}

Key payload fields

Answer types

Each object in the answers array includes a type, the answer value, and a field object identifying the question. Typeform supports the following answer types:

The answers array only contains answered questions. If a question is not required and was skipped, or was bypassed by Logic Jump, it will not appear in the payload.

Security with HMAC signatures

Typeform supports HMAC SHA-256 signatures to verify that webhook payloads genuinely originated from Typeform. When you configure a secret on your webhook, Typeform signs the entire payload body and includes the signature in the Typeform-Signature header.

The signature format is sha256={base64_encoded_hash}, where the hash is generated using HMAC SHA-256 with your secret as the key and the raw request body as the message, then base64-encoded.

The secret must be explicitly set when creating or updating the webhook. If you don't supply the secret field in your API call, the Typeform-Signature header will not be included in deliveries.

Setting up Typeform webhooks

Via the Typeform UI

1. Sign in to Typeform and open the form you want to configure.
2. Click Connect in the top menu.
3. Click the Webhooks tab.
4. Click Add a webhook and enter your endpoint URL.
5. Toggle the webhook ON (webhooks are OFF by default).
6. Optionally, click Edit to add a secret for HMAC signature verification.
7. Click Save changes.

Via the Webhooks API

Create or update a webhook by sending a PUT request:

curl --request PUT \
  --url https://api.typeform.com/forms/{form_id}/webhooks/{tag} \
  --header 'Authorization: Bearer {your_access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://your-endpoint.com/webhooks/typeform",
    "enabled": true,
    "secret": "your_hmac_secret",
    "verify_ssl": true,
    "event_types": {
      "form_response": true,
      "form_response_partial": false
    }
  }'

API parameters:

Base URLs:

• Standard: https://api.typeform.com
• EU Data Center: https://api.eu.typeform.com or https://api.typeform.eu

Best practices when working with Typeform webhooks

Verifying HMAC signatures

When processing webhooks from Typeform, always verify the HMAC signature to ensure requests genuinely originated from your Typeform account.

Node.js

const crypto = require('crypto');
const express = require('express');
const app = express();

app.use(express.raw({ type: 'application/json' }));

function verifyTypeformSignature(receivedSignature, payload, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('base64');
  return receivedSignature === `sha256=${hash}`;
}

app.post('/webhooks/typeform', (req, res) => {
  const signature = req.headers['typeform-signature'];

  if (!signature || !verifyTypeformSignature(signature, req.body.toString(), process.env.TYPEFORM_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook
  res.status(200).send('OK');
});

Python

import hmac
import hashlib
import base64
import os
from flask import Flask, request, abort

app = Flask(__name__)

def verify_typeform_signature(received_signature, payload, secret):
    digest = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).digest()
    computed = f"sha256={base64.b64encode(digest).decode()}"
    return hmac.compare_digest(computed, received_signature)

@app.route('/webhooks/typeform', methods=['POST'])
def handle_typeform_webhook():
    signature = request.headers.get('Typeform-Signature')

    if not signature or not verify_typeform_signature(
        signature,
        request.get_data(),
        os.environ['TYPEFORM_WEBHOOK_SECRET']
    ):
        abort(401)

    # Process webhook
    return 'OK', 200

Respond immediately to avoid retries

Typeform has a strict 30-second timeout. If your endpoint doesn't respond with a 2xx status code within that window, Typeform marks the delivery as failed and begins retrying. Always acknowledge the webhook immediately and process the data asynchronously.

Use the token for idempotency

Each submission includes a form_response.token field — a unique identifier for that specific response. Because Typeform's retry policy can result in duplicate deliveries, use the token to implement idempotent processing:

async function processTypeformSubmission(payload) {
  const token = payload.form_response.token;

  // Check if already processed
  const exists = await redis.get(`processed:${token}`);
  if (exists) {
    console.log(`Submission ${token} already processed, skipping`);
    return;
  }

  // Process the submission
  await handleSubmission(payload);

  // Mark as processed with TTL
  await redis.setex(`processed:${token}`, 86400, '1'); // 24-hour TTL
}

Match answers to questions using field IDs

Typeform's payload structure separates the form definition (questions) from the answers. Use the field.id or field.ref to reliably match answers to their questions rather than relying on array position:

function getAnswerByRef(answers, ref) {
  return answers.find(answer => answer.field.ref === ref);
}

function processSubmission(payload) {
  const { definition, answers } = payload.form_response;

  // Use refs for stable identification across form edits
  const emailAnswer = getAnswerByRef(answers, 'email_field_ref');
  const nameAnswer = getAnswerByRef(answers, 'name_field_ref');

  // Remember: unanswered questions won't be in the answers array
  const email = emailAnswer?.email;
  const name = nameAnswer?.text;
}

Handle missing answers gracefully

Since the answers array only includes answered questions, always check for missing answers rather than assuming every field will be present:

function extractAnswers(payload) {
  const { answers } = payload.form_response;
  const answerMap = {};

  for (const answer of answers) {
    answerMap[answer.field.id] = answer;
  }

  return {
    name: answerMap['JwWggjAKtOkA']?.text ?? null,
    email: answerMap['SMEUb7VJz92Q']?.email ?? null,
    rating: answerMap['WOTdC00F8A3h']?.number ?? null,
  };
}

Typeform webhook limitations and pain points

Aggressive retry behaviour and duplicate deliveries

The Problem: Typeform's retry policy can flood your endpoint with duplicate requests. If your webhook doesn't respond within 30 seconds, Typeform immediately begins retrying every 2–3 minutes for up to 10 hours. Developers have reported receiving a continuous stream of repeated requests for a single form submission, sometimes leading to duplicate records in downstream systems or duplicate messages sent to customers.

Why It Happens: Typeform's philosophy is that it's better to deliver a webhook twice than not at all. Any response other than a 2xx status code (including no response within the 30-second window) triggers retries. Because the retry interval is short (2–3 minutes) and the retry window is long (10 hours), a single slow endpoint can generate hundreds of retry attempts.

Workarounds:

• Always respond with a 200 status code immediately and process asynchronously.
• Implement idempotency using the form_response.token to detect and skip duplicate deliveries.
• Monitor your endpoint's response times to ensure they stay well under 30 seconds.

How Hookdeck Can Help: Hookdeck automatically deduplicates webhook deliveries based on payload content or custom identifiers like the submission token. Its configurable retry policies with exponential backoff replace Typeform's aggressive fixed-interval retries, preventing retry storms while still ensuring reliable delivery.

No way to disable retries

The Problem: Typeform does not provide any option to disable webhook retries. Even in scenarios where a retry is undesirable (such as when the first request succeeded but the response was delayed) Typeform will send additional requests. This makes it impossible to prevent duplicate processing at the source.

Why It Happens: The retry policy is built into Typeform's infrastructure with no user-configurable options. It's a one-size-fits-all approach designed to maximize delivery reliability.

Workarounds:

• Implement idempotent processing on your endpoint as your primary defence.
• Use a response token cache to track which submissions have already been handled.
• Ensure your endpoint always responds quickly with a 2xx status to minimise unnecessary retries.

How Hookdeck Can Help: Hookdeck provides fully configurable retry policies, including the ability to set retry counts, intervals, and backoff strategies. You can also disable retries entirely for specific webhook sources, giving you complete control over delivery behaviour.

Automatic webhook disabling

The Problem: If a webhook fails consistently, Typeform will automatically disable it without requiring your confirmation. Specifically, if a webhook fails 100% of deliveries within 24 hours with more than 300 attempts, or within 5 minutes with 100 attempts, Typeform disables it. A 404 Not Found or 410 Gone response disables the webhook immediately with no retries. Once disabled, you won't receive any further webhook deliveries until you manually re-enable it.

Why It Happens: Typeform auto-disables webhooks to protect its infrastructure from wasting resources on endpoints that are consistently failing, and to prevent overwhelming endpoints that may be experiencing issues.

Workarounds:

• Monitor webhook status and set up alerts for when webhooks are disabled (Typeform sends an email notification).
• Ensure your endpoint never returns 404 or 410 status codes accidentally.
• Use health checks to detect endpoint issues before Typeform's thresholds are reached.
• After resolving issues, use the Responses API to backfill any submissions missed during the outage.

How Hookdeck Can Help: Hookdeck acts as a reliable intermediary that always accepts webhook deliveries from Typeform, preventing auto-disabling. Failed deliveries are stored in Hookdeck's dead letter queue for inspection and replay, so you never lose submissions even during downstream outages.

No custom header support

The Problem: Typeform does not allow you to add custom headers to webhook deliveries. You cannot include headers like Authorization: Bearer, X-API-Key, X-Tenant-ID, or any other custom headers that your endpoint or downstream systems may require for authentication or routing.

Why It Happens: Typeform's webhook implementation sends a fixed set of headers with each delivery. The only authentication mechanism available is the HMAC signature in the Typeform-Signature header.

Workarounds:

• Include authentication tokens as query parameters in your webhook URL (less secure, visible in logs).
• Deploy a lightweight proxy or middleware service that receives the Typeform webhook and adds required headers before forwarding.
• Use hidden fields in your typeform to pass tenant or routing information in the payload body.

How Hookdeck Can Help: Hookdeck's transformations allow you to add, modify, or remove headers on incoming webhook requests before forwarding them to your endpoint. This eliminates the need for a custom proxy and lets you add any authentication or routing headers your downstream systems require.

No payload customisation

The Problem: Typeform does not offer any ability to customise the webhook payload structure. The JSON format is fixed, and you cannot add, remove, or transform fields before delivery. If your downstream system expects a different payload format, you need to build a transformation layer.

Why It Happens: Typeform's webhook system delivers a standardised payload for all integrations. There is no template engine or transformation configuration available.

Workarounds:

• Build a middleware service that receives the standard Typeform payload, transforms it, and forwards it to your destination.
• Use an integration platform (like Make or Zapier) to transform the payload, though this adds latency and cost.
• Parse and restructure the payload in your own webhook handler.

How Hookdeck Can Help: Hookdeck's transformation capabilities allow you to reshape webhook payloads in-flight using JavaScript, converting Typeform's standard format to match any target system's requirements without building custom middleware.

No static IP addresses for whitelisting

The Problem: Typeform is hosted on AWS and uses dynamic IP addresses. There is no guaranteed static IP range you can use to restrict access to your webhook endpoint. If your infrastructure requires IP-based access control, you cannot reliably whitelist Typeform's webhook traffic.

Why It Happens: Typeform runs on AWS infrastructure, which uses dynamic IP address allocation. Providing a stable set of IPs for webhook delivery is not currently supported.

Workarounds:

• Rely on HMAC signature verification instead of IP whitelisting as your primary authentication method.
• If you must use IP restrictions, place a proxy in front of your endpoint that verifies Typeform's HMAC signature and forwards validated requests.
• Use a webhook gateway service with static IPs.

How Hookdeck Can Help: Hookdeck provides static IP addresses for webhook delivery, enabling you to configure IP-based firewall rules on your endpoint while still receiving Typeform webhooks reliably.

API-created webhooks not visible in the UI

The Problem: Webhooks created via the Typeform Webhooks API do not appear in the typeform's workspace UI. This means you cannot see their configuration, delivery status, or recent delivery attempts through the Typeform builder. Delivery tracking via the UI (the last 50 delivery attempts) is only available for webhooks created through the workspace.

Why It Happens: Typeform maintains separate visibility for UI-created and API-created webhooks. This is documented behaviour, not a bug, but it creates a fragmented management experience.

Workarounds:

• Manage API-created webhooks entirely through the API, using GET /forms/{form_id}/webhooks to list and inspect them.
• Build your own monitoring dashboard that tracks API-created webhook status.
• Create webhooks through the UI when you need delivery visibility, and reserve the API for programmatic use cases.

How Hookdeck Can Help: Hookdeck's dashboard provides complete visibility into all webhook deliveries regardless of how they were created, including delivery status, latency, response codes, and full request/response details for debugging.

No per-form webhook management at scale

The Problem: Typeform does not support account-level or workspace-level webhooks. Each webhook must be configured per form, which becomes unwieldy when managing dozens or hundreds of forms that all need to send data to the same endpoint.

Why It Happens: Typeform's webhook architecture is scoped to individual forms, with no global webhook configuration option.

Workarounds:

• Use the Webhooks API to programmatically create webhooks across all forms when new forms are created.
• Build automation that listens for new form creation events and auto-configures webhooks.
• Maintain a webhook provisioning script as part of your deployment pipeline.

How Hookdeck Can Help: Hookdeck allows you to configure a single destination with routing rules that apply across multiple webhook sources, simplifying management for high-volume Typeform deployments.

Limited delivery visibility and no dead letter queue

The Problem: Typeform provides minimal visibility into webhook delivery success or failure. For UI-created webhooks, you can view the last 50 delivery attempts. For API-created webhooks, there is no delivery log at all. Webhooks that fail after all retries are exhausted are simply lost — there is no dead letter queue or mechanism to replay failed deliveries.

Why It Happens: Typeform's webhook infrastructure is designed primarily for reliability through retries, not for observability or manual intervention. The 50-delivery log limit and lack of a dead letter queue reflect a system optimised for automated delivery rather than developer debugging.

Workarounds:

• Implement your own logging of received webhooks for gap analysis.
• Use the Responses API to periodically reconcile received webhooks against submitted responses.
• Monitor your webhook endpoint's health independently to detect failures before they escalate.

How Hookdeck Can Help: Hookdeck provides a full event log with searchable delivery history, detailed request and response inspection, and an automatic dead letter queue for failed deliveries. You can inspect, debug, and replay failed webhooks at any time, ensuring no submissions are permanently lost.

No development/production environment separation

The Problem: Typeform doesn't provide built-in support for separating development and production webhook environments. The webhook URL is configured directly on the form, and there's no staging or environment-switching mechanism. Testing webhooks during development requires changing the URL or duplicating forms.

Why It Happens: Typeform's webhook configuration is a simple URL field per form, with no concept of environments or deployment stages.

Workarounds:

• Duplicate your form and use the copy for development testing.
• Add multiple webhooks to the same form (one for production, one for development) and toggle them on/off as needed.
• Use a tunnelling service like Hookdeck's CLI during local development to receive webhooks at a temporary URL.
• Use the built-in Test button in the Typeform UI to send sample payloads to your development endpoint.

How Hookdeck Can Help: Hookdeck supports multiple destinations per source, allowing you to route Typeform webhooks to both production and development endpoints simultaneously. You can also use Hookdeck's CLI to tunnel webhooks to your local machine for testing without modifying your Typeform configuration.

Testing Typeform webhooks

Use the built-in test feature

The Typeform webhook configuration includes a Test webhook button that sends a sample payload to your endpoint. However, be aware that test payloads use sample data and may differ slightly from real submissions, particularly around field types and hidden field values.

Use a request inspector

Before building your handler, inspect real Typeform payloads:

1. Create a temporary webhook URL using a service like Hookdeck's Console.
2. Configure it as your form's webhook endpoint.
3. Submit a real response to your typeform.
4. Inspect the full payload structure, headers, and signature.

Validate in staging

Test your webhook integration with realistic scenarios:

• Single form submission with all question types answered.
• Submission with optional questions skipped (to test missing answer handling).
• Rapid successive submissions (to test idempotency under load).
• Forms with Logic Jumps (to test varied answer arrays).
• Partial response webhooks if enabled.

Conclusion

Typeform webhooks provide a straightforward way to integrate form submissions with external systems in real-time. The JSON payload is comprehensive, including full form definitions alongside answers, which simplifies processing. HMAC signature verification offers a solid foundation for security, and the retry policy ensures reasonable delivery reliability out of the box.

However, the limitations around retry control, custom headers, payload customisation, and delivery visibility mean that production deployments, especially those handling high volumes or requiring complex routing, need careful engineering. Implementing idempotent processing, asynchronous acknowledgment, and signature verification will address most common issues.

For straightforward integrations with reliable endpoints and moderate submission volumes, Typeform's built-in webhook system works well. For high-volume form processing, multi-destination routing, or mission-critical workflows where delivery guarantees and observability matter, webhook infrastructure like Hookdeck can address Typeform's limitations, providing configurable retries, payload transformation, automatic deduplication, static IPs, and comprehensive delivery monitoring without modifying your Typeform configuration.