Webhooks

Method 1: Using the Dashboard

1. Navigate to your Workspace Settings
2. Go to the "Webhooks" section
3. Click "Create New Webhook"
4. Enter your webhook URL (must be HTTPS)
5. Select which events you want to receive
6. Choose specific forms or listen to all forms
7. Save and activate your webhook

Method 2: Using the API

// Request
POST /api/v1/webhooks
Content-Type: application/json
X-API-Key: workform_your_api_key

{
  "url": "https://your-server.com/webhook",
  "events": ["form.submitted", "form.response.updated"],
  "description": "Send submissions to CRM",
  "isActive": true,
  "formId": "abc123" // Optional: specific form
}

// Response
{
  "success": true,
  "message": "Webhook created successfully.",
  "data": {
    "id": "wh_abc123",
    "url": "https://your-server.com/webhook",
    "events": ["form.submitted", "form.response.updated"],
    "description": "Send submissions to CRM",
    "isActive": true,
    "secret": "whsec_...", // Use for signature verification
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Request Signing

All webhook requests include a signature in the X-WorkForm-Signature header. Use this to verify the request came from WorkForm.

// Example: Verifying webhook signature (Node.js)
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-workform-signature'];
  const secret = 'whsec_...'; // From webhook creation
  
  if (!verifyWebhookSignature(req.body, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook
  console.log('Event:', req.body.event);
  console.log('Data:', req.body.data);
  
  res.status(200).send('OK');
});

Delivery Expectations

• Webhooks are delivered in near real-time (typically within 1-2 seconds)
• Your endpoint should respond with a 2xx status code within 5 seconds
• Any non-2xx response or timeout will trigger a retry

Automatic Retries

If delivery fails, WorkForm automatically retries with exponential backoff:

After 5 failed attempts, the webhook will be marked as failed and you'll receive an email notification.

Local Development

Use tools like ngrok or localtunnel to expose your local server for webhook testing:

# Using ngrok
ngrok http 3000

# This will give you a public URL like:
# https://abc123.ngrok.io

# Use this URL when creating your webhook:
# https://abc123.ngrok.io/webhook

Test Event Trigger

You can trigger a test event from the dashboard or API:

POST /api/v1/webhooks/wh_abc123/test
X-API-Key: workform_your_api_key

{
  "event": "form.submitted"
}

// This sends a sample payload to your webhook URL

Webhook Logs

View webhook delivery attempts, response codes, and payloads in your workspace settings under "Webhooks" → "Logs". This helps debug failed deliveries and verify your integration.