Webhooks

Learn how to integrate real-time notifications into your application

What are webhooks?

Webhooks are automated messages sent from apps when something happens. They have a message—or payload—and are sent to a unique URL (your endpoint).

Instead of constantly checking our API for new data (polling), webhooks push data to your application in real-time when events occur. This is more efficient and provides instant notifications.

When a user submits a survey or form on your website, Ask Users can instantly notify your application via webhook, allowing you to:

Automatically sync data to your CRM (Salesforce, HubSpot, etc.)
Send notifications to your team via Slack or email
Trigger custom workflows in your application
Update your database in real-time
Feed data into analytics platforms

How webhooks work

Event occurs

A user submits a survey or form on your website. Ask Users captures this event and prepares to notify your application.

Webhook triggered

Ask Users checks which webhooks are configured for this event. If your webhook is set up to receive this event type, we prepare the payload with all relevant data.

HTTP POST request sent

We send an HTTP POST request to your webhook URL with the event data in JSON format. The request includes security headers (HMAC signature) to verify authenticity.

Your endpoint processes the data

Your application receives the webhook, verifies the signature, and processes the data. You can store it in your database, trigger notifications, update records, or perform any custom logic.

Response and retry

Your endpoint should respond with a 2xx status code (typically 200 OK) within 30 seconds. If we don't receive a successful response, we'll automatically retry the delivery up to 5 times with exponential backoff:

Attempt 1: Immediate
Attempt 2: 1 minute later
Attempt 3: 5 minutes later
Attempt 4: 15 minutes later
Attempt 5: 1 hour later
Attempt 6: 6 hours later

Key features

Secure delivery

All webhooks are signed with HMAC-SHA256 signatures to verify authenticity

Automatic retries

Failed deliveries are automatically retried up to 5 times with exponential backoff

Real-time delivery

Webhooks fire immediately when events occur, typically within milliseconds

Event deduplication

Unique event IDs prevent duplicate processing even during retries

Supported events

`survey.response.created`

Triggered when a new survey response is submitted. Contains the complete response data, including all answers, respondent information, and survey metadata.

`form.submission.created`

Triggered when a new form submission is created. Includes all form field data, submission status, and form configuration details.

Quick start

Configure webhook in dashboard

1. Go to your dashboard

2. Navigate to Settings → Webhooks

3. Click Create Webhook

4. Enter your endpoint URL and select event types

5. Save and copy your secret key

Test your webhook

Submit a test survey or form to trigger your webhook and verify it's working correctly. Check the delivery logs in your dashboard to see the request and response.

Webhook reference implementation

Here's a complete example of how to create and verify a webhook endpoint in your application:

// Node.js/Express example
const crypto = require('crypto');

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

  // Verify signature (see security section)
  if (!verifySignature(req.body, signature)) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook
  const { event_type, data } = req.body;

  // Return 200 OK immediately
  res.status(200).send('OK');

  // Process async
  processWebhookAsync(event_type, data);
});

Webhook payload example

Here's an example of what a webhook payload looks like:

{
  "event_type": "survey.response.created",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "response": {
      "id": "response-uuid",
      "survey_id": "survey-uuid",
      "response_data": {
        "question-id-1": "Answer 1",
        "question-id-2": "Answer 2"
      },
      "completion_status": "completed",
      "created_at": "2025-01-15T10:30:00.000Z"
    },
    "survey": {
      "id": "survey-uuid",
      "title": "Product Feedback Survey"
    }
  }
}

Security & verification

Always verify webhook signatures to ensure requests came from Ask Users. Every webhook includes an X-Webhook-Signature header with an HMAC-SHA256 signature.

Verification example (Node.js)

const crypto = require('crypto');

function verifySignature(payload, signature) {
  const secret = process.env.ASKUSERS_WEBHOOK_SECRET;
  const payloadString = JSON.stringify(payload);

  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payloadString)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Verification example (Python)

import hmac
import hashlib
import os

def verify_signature(payload: str, signature: str) -> bool:
    secret = os.environ['ASKUSERS_WEBHOOK_SECRET']

    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected_signature)

Best practices

1. Respond quickly

Always return 200 OK immediately, then process the webhook asynchronously. Keep response time under 30 seconds to avoid timeouts.

2. Handle duplicate deliveries

Use the event_id to deduplicate events. Store processed event IDs to prevent duplicate processing. This is important because retries may cause the same event to be delivered multiple times.

3. Use HTTPS

Always use HTTPS URLs for webhook endpoints in production to ensure data security and prevent man-in-the-middle attacks.

4. Monitor delivery logs

Check your webhook delivery logs in the dashboard to monitor success rates and identify issues. Logs show the full request/response for troubleshooting.

5. Implement proper error handling

Wrap your webhook processing logic in try-catch blocks and log errors. Return appropriate HTTP status codes: 200-299 for success, 4xx for client errors (which won't be retried), 5xx for server errors (which will trigger retries).

No-code integration

Don't want to write code? Use webhooks with Zapier or Make:

Create a new "Catch Webhook" trigger in Zapier or Make
Copy the webhook URL provided
Create a webhook in Ask Users with that URL
Test it by submitting a form or survey
Build your automation workflow!

Need help?

If you have questions or need assistance with webhooks:

• Check delivery logs in your dashboard
• Review the troubleshooting section above
• Contact us at support@askusers.org