Form webhooks

Receive real-time notifications when users submit your forms

What are webhooks?

Webhooks are HTTP callbacks that notify your application when specific events occur in Ask Users. When a user submits a form, Ask Users can send a POST request to your specified endpoint with the submission data in real-time.

This allows you to integrate form submissions with your existing systems, trigger automated workflows, send notifications, or process data immediately without polling the API.

How webhooks work

1.You configure a webhook URL in your form settings
2.A user submits your form
3.Ask Users immediately sends a POST request to your webhook URL with the submission data
4.Your server processes the data and responds with a 200 status code

Form submission events

Form webhooks trigger on the following event:

form.submission.created

POST

Triggered immediately when a user successfully submits a form. The webhook payload includes the form ID, submission ID, timestamp, and all question responses with their values.

Includes:

• Submission ID and timestamp
• Form ID and name
• All question responses with labels and values
• User information (if authenticated)
• Metadata (IP address, user agent, referrer)

Setting up webhooks

Follow these steps to configure webhooks for your form:

Create an endpoint on your server

Set up an HTTP endpoint that can receive POST requests. This endpoint should accept JSON data and return a 200 status code to acknowledge receipt.

// Example Node.js endpoint
app.post('/webhooks/form-submission', (req, res) => {
  const submission = req.body;

  // Process submission data
  console.log('Received submission:', submission);

  // Return 200 to acknowledge
  res.status(200).send('OK');
});

2
Navigate to form settings
Go to your form in the dashboard, click "Settings", and find the "Webhooks" section.
3
Add webhook URL
Enter your endpoint URL (must be HTTPS in production) and click "Add webhook".
Example URL:
https://api.yourdomain.com/webhooks/form-submission
4
Configure secret (optional but recommended)
Set a secret key to verify webhook authenticity. Ask Users will include this in the request headers for verification.
5
Test your webhook
Use the "Send test webhook" button in the dashboard to verify your endpoint is working correctly.

Security requirements

Webhook URLs must use HTTPS in production environments. HTTP URLs are only allowed for local development (localhost). Always verify webhook signatures to prevent unauthorized requests.

Payload structure

The webhook POST request includes a JSON payload with the following structure:

Example payload

{
  "event": "form.submission.created",
  "timestamp": "2025-11-20T14:30:00.000Z",
  "data": {
    "submission": {
      "id": "sub_abc123def456",
      "createdAt": "2025-11-20T14:30:00.000Z",
      "formId": "form_xyz789",
      "formName": "Contact Form",
      "responses": [
        {
          "questionId": "q1",
          "questionText": "What is your name?",
          "questionType": "text",
          "value": "John Doe"
        },
        {
          "questionId": "q2",
          "questionText": "What is your email?",
          "questionType": "email",
          "value": "john@example.com"
        },
        {
          "questionId": "q3",
          "questionText": "How did you hear about us?",
          "questionType": "select",
          "value": "Social media"
        },
        {
          "questionId": "q4",
          "questionText": "Your message",
          "questionType": "textarea",
          "value": "I'm interested in your product..."
        }
      ],
      "user": {
        "id": "user_123",
        "email": "john@example.com",
        "name": "John Doe"
      },
      "metadata": {
        "ipAddress": "192.168.1.1",
        "userAgent": "Mozilla/5.0...",
        "referrer": "https://example.com/landing"
      }
    }
  }
}

Request headers

X-AskUsers-Signature

HMAC SHA-256 signature for webhook verification

X-AskUsers-Event

Event type (form.submission.created)

Content-Type

application/json

Testing webhooks

It's important to test your webhooks before deploying to production. Here are some methods:

Dashboard test button

Use the "Send test webhook" button in your form settings to send a sample payload to your endpoint. This helps verify that your server can receive and process webhook requests.

Test payloads include sample data that mimics a real submission.

Local development with ngrok

Use ngrok or similar tools to expose your local development server to the internet, allowing Ask Users to send webhooks to your local machine.

ngrok http 3000

Webhook testing services

Use services like webhook.site or requestbin.com to inspect webhook payloads without setting up your own server.

• webhook.site
• requestbin.com
• hookbin.com

Monitor webhook logs

Check the webhook logs in your form settings to see delivery status, response codes, and any errors. This helps debug issues with your webhook endpoint.

Common use cases

Here are some popular ways to use form webhooks:

Email notifications

Send immediate email notifications to your team when a high-priority form is submitted, such as support requests or sales inquiries.

CRM integration

Automatically create or update records in your CRM (Salesforce, HubSpot, etc.) when lead capture forms are submitted.

Slack/Teams notifications

Post form submissions to Slack or Microsoft Teams channels to keep your team informed in real-time about new responses.

Database storage

Store form submissions in your own database for custom reporting, analytics, or long-term archiving.

Automated workflows

Trigger complex multi-step workflows in tools like Zapier, Make, or n8n based on form submissions.

Payment processing

Initiate payment collection or subscription creation when users submit registration or order forms.

Error handling

Ask Users implements robust error handling and retry logic for webhooks:

Retry mechanism

If your endpoint fails to respond with a 200 status code, Ask Users will automatically retry the webhook with exponential backoff:

• Retry 1: After 1 minute
• Retry 2: After 5 minutes
• Retry 3: After 15 minutes
• Retry 4: After 1 hour
• Retry 5: After 6 hours

Timeout and failure

Webhook requests timeout after 30 seconds. If all retry attempts fail, the webhook is marked as failed and you'll receive an email notification.

Important: Failed webhooks are stored for 7 days and can be manually retried from the webhook logs in your dashboard.

Common error responses

Connection refused / Timeout

Your endpoint is unreachable. Check that your server is running and accessible.

SSL certificate error

Your HTTPS certificate is invalid or expired. Update your SSL certificate.

5xx server errors

Your server encountered an error processing the webhook. Check your application logs.

Best practices

Respond quickly: Return a 200 status code as soon as you receive the webhook. Process data asynchronously if needed.
Verify signatures: Always verify the X-AskUsers-Signature header to ensure requests are coming from Ask Users.
Handle duplicates: Implement idempotency using the submission ID to avoid processing the same webhook multiple times.
Log webhook requests: Keep logs of all webhook requests for debugging and auditing purposes.
Use HTTPS: Always use HTTPS endpoints in production. Never use HTTP for webhook URLs.
Set up monitoring: Monitor your webhook endpoint for errors and set up alerts for failed deliveries.
Handle errors gracefully: Implement proper error handling so temporary failures don't cause data loss.
Test thoroughly: Test your webhook implementation with both successful and error scenarios before going live.