How to Receive Typeform Webhooks: A Complete Guide

Updated October 3, 20259 min read

Typeform webhooks allow you to get real-time notifications for new form submissions, enabling you to automate workflows, sync data with your CRM, and build dynamic applications. This guide will walk you through everything you need to know to receive and process Typeform webhooks effectively.

What Are Typeform Webhooks?

A Typeform webhook is an automated message sent from Typeform to a URL you specify when a new response is submitted to your form. Instead of you having to poll the Typeform API for new responses, Typeform actively sends you the data as it happens.

This is incredibly useful for triggering actions in other systems, such as adding a new lead to your CRM, sending a confirmation email, or updating a database.

Setting Up Your Typeform Webhook

Step 1: Create a Webhook Receiver Endpoint

First, you need a publicly accessible URL that can receive POST requests with a JSON payload. This endpoint is where Typeform will send the webhook data. Your endpoint should:

  • Be able to handle POST requests.
  • Respond with a 2xx status code (e.g., 200 OK) to acknowledge receipt.
  • Be secure (HTTPS is highly recommended).
// Node.js Express example for receiving a Typeform webhook
const express = require('express'); const crypto = require('crypto'); const app = express(); // Use express.json() for automatic parsing, but we need the raw body for signature verification app.use(express.json({ verify: (req, res, buf) => { req.rawBody = buf; } })); const TYPEFORM_SECRET = process.env.TYPEFORM_SECRET; app.post('/typeform-webhook', (req, res) => { const signature = req.headers['typeform-signature']; if (signature && TYPEFORM_SECRET) { const hash = crypto .createHmac('sha256', TYPEFORM_SECRET) .update(req.rawBody) .digest('base64'); const calculatedSignature = `sha256=${hash}`; if (crypto.timingSafeEqual(Buffer.from(calculatedSignature), Buffer.from(signature))) { console.log('Signature verified successfully!'); // Process the webhook payload console.log(req.body.form_response.answers); res.status(200).send('OK'); } else { console.error('Signature verification failed.'); res.status(401).send('Invalid signature'); } } else { console.warn('No signature or secret provided. Skipping verification.'); // Process the webhook payload without verification (not recommended for production) console.log(req.body.form_response.answers); res.status(200).send('OK'); } }); app.listen(3000, () => console.log('Server running on port 3000'));

Step 2: Add the Webhook to Your Typeform

  1. Go to your Typeform workspace and open the form you want to add the webhook to.
  2. Click on the "Connect" tab.
  3. Find and click on "Webhooks".
  4. Click "Add a webhook" and paste your endpoint URL.
  5. If you want to secure your webhook, you can generate a secret key here. Copy it and save it as an environment variable in your application.
  6. Save the webhook and turn it on.

Securing Your Typeform Webhooks

Why Signature Verification is Essential

Verifying the webhook signature is crucial. It confirms that the request was sent by Typeform and not by a malicious third party. This prevents fake submissions and protects your application from attacks.

How Typeform Signatures Work

When you set a secret for your webhook, Typeform includes a Typeform-Signature header in each request. This header contains a HMAC-SHA256 hash of the request payload, signed with your secret key.

Typeform-Signature: sha256=...

Your application should calculate the same hash using the received payload and your secret key, and then compare it to the signature from the header.

Testing Your Webhook Integration

Using the Typeform "Send a test request" feature

In the Typeform webhook settings, you can send a test request to your endpoint. This is a great way to verify that your endpoint is reachable and can handle the basic payload structure.

Local Development and Testing

For local development, your server is not publicly accessible. You can use a tool like ngrok to create a secure tunnel to your local machine. This gives you a public URL that you can use in your Typeform webhook settings.

# Install ngrok and run it to expose your local server
ngrok http 3000

Ngrok will give you a public URL (e.g., `https://random-string.ngrok.io`) that you can use as your webhook URL in Typeform.

Best Practices for Production

Respond Quickly

Typeform expects a response within 30 seconds. If your processing logic takes longer, Typeform will consider the delivery as failed. Acknowledge the request immediately by returning a 200 OK status, and then process the data asynchronously using a background job or a queue.

Handle Retries

If your endpoint fails to respond with a 2xx status, Typeform will retry sending the webhook. Your application should be prepared to handle potential duplicate events. You can do this by checking the `event_id` from the payload to see if you have already processed that event.

Monitor and Log

Keep logs of incoming webhooks and any errors that occur during processing. This is invaluable for debugging issues. Set up monitoring to alert you if your webhook endpoint is failing consistently.

Debug Typeform Webhooks with Hooklistener

Hooklistener simplifies debugging Typeform webhooks by allowing you to capture, inspect, and replay events. It's the perfect tool for ensuring your integration is robust and reliable.

Start Debugging Typeform Webhooks →

Related Webhook Resources

Webhook Fundamentals

Learn the basics of webhooks and how they work

Free Webhook Tester

Test and debug webhooks instantly