G
SkunkGlobal/Docs/Forms
SkunkForms

Webhooks

Send form submissions to external services automatically with webhooks.

What are Webhooks?

Webhooks are HTTP requests that SkunkForms sends to external URLs when forms are submitted. They enable real-time integrations with CRMs, email marketing platforms, project management tools, and custom applications.

Instead of checking for new submissions manually, external services receive data instantly.

Setting Up Webhooks

  1. Go to Form Settings > Webhooks
  2. Click Add Webhook
  3. Enter the target URL
  4. Configure payload and headers
  5. Test the connection
  6. Save settings

Webhooks fire immediately when forms are submitted successfully.

Webhook URL

The URL where SkunkForms will send HTTP POST requests:

Examples

https://hooks.zapier.com/hooks/catch/123456/abcdef/
https://api.mailchimp.com/3.0/lists/abc123/members/
https://your-app.com/api/leads/

Requirements

  • Must be HTTPS (secure connection)
  • Must respond within 30 seconds
  • Should return 200-299 status code for success

Payload Format

SkunkForms sends form data as JSON in the request body:

Basic Payload

{
  "form_id": 42,
  "submission_id": 1234,
  "submitted_at": "2025-02-09T10:30:00Z",
  "form_title": "Contact Form",
  "fields": {
    "name": "John Smith",
    "email": "john@example.com",
    "message": "Hello world",
    "consent": true
  },
  "meta": {
    "user_agent": "Mozilla/5.0...",
    "ip_address": "192.168.1.100",
    "referrer": "https://example.com/contact/"
  }
}

File Uploads

Files are represented as objects with download URLs:

{
  "resume": {
    "filename": "john-smith-resume.pdf",
    "size": 245760,
    "url": "https://yoursite.com/wp-content/uploads/skunkforms/2025/02/resume.pdf",
    "mime_type": "application/pdf"
  }
}

Custom Headers

Add authentication and custom headers:

Examples

Authorization: Bearer your-api-token
X-API-Key: abc123xyz789
Content-Type: application/json

Headers are useful for API authentication and request routing.

Webhook Security

HTTPS Required

All webhook URLs must use HTTPS to protect sensitive form data in transit.

Request Signing

SkunkForms includes an HMAC signature for webhook verification:

X-SkunkForms-Signature: sha256=abc123def456...

Verify this signature to ensure requests actually came from SkunkForms.

IP Allowlisting

Webhooks originate from your WordPress server's IP address. Some services require allowlisting this IP.

Popular Integrations

Zapier

Connect to 3,000+ apps through Zapier:

URL: https://hooks.zapier.com/hooks/catch/[user]/[hook]/

Make (Integromat)

Automate workflows with Make:

URL: https://hook.integromat.com/[webhook-id]

Slack

Post submissions to Slack channels:

URL: https://hooks.slack.com/services/T00/B00/XXX

Mailchimp

Add subscribers automatically:

URL: https://[dc].api.mailchimp.com/3.0/lists/[list-id]/members/
Headers: Authorization: apikey [your-api-key]

HubSpot

Create contacts and deals:

URL: https://api.hubapi.com/crm/v3/objects/contacts/
Headers: Authorization: Bearer [access-token]

Testing Webhooks

Webhook Inspector

Use tools like webhook.site to inspect payloads:

  1. Get a test URL from webhook.site
  2. Add it as your webhook URL
  3. Submit your form
  4. View the received payload

Request Bin

Similar testing with RequestBin or Hookbin services.

Local Testing

Use ngrok to test webhooks locally:

ngrok http 3000
# Use the HTTPS URL as your webhook endpoint

Error Handling

Retry Logic

If a webhook fails (non-200 status code), SkunkForms retries:

  • 1st retry: After 5 seconds
  • 2nd retry: After 30 seconds
  • 3rd retry: After 5 minutes
  • Final retry: After 1 hour

After 4 failed attempts, the webhook is marked as failed.

Error Notifications

Configure email notifications for webhook failures:

  1. Go to Form Settings > Webhooks > Error Handling
  2. Enter notification email address
  3. Choose failure conditions (all failures vs repeated failures)

Common Errors

  • Timeout — Endpoint took longer than 30 seconds
  • DNS Error — URL hostname couldn't be resolved
  • SSL Error — Certificate issues with HTTPS endpoint
  • 404 Not Found — Webhook URL doesn't exist
  • 500 Server Error — Target server had an internal error

Debugging Webhooks

Webhook Logs

View recent webhook attempts in SkunkForms > Webhooks > Logs:

  • Request URL
  • Response status code
  • Response time
  • Error messages
  • Retry attempts

Testing Mode

Enable test mode to see webhook payloads without actually sending them.

Payload Inspector

View the exact JSON payload before sending to debug formatting issues.

Best Practices

Endpoint Reliability

  • Use reliable hosting for webhook endpoints
  • Implement proper error handling
  • Return appropriate HTTP status codes
  • Respond quickly (under 5 seconds preferred)

Data Validation

  • Validate incoming webhook data
  • Check required fields are present
  • Sanitize data before processing
  • Verify webhook signatures

Monitoring

  • Monitor webhook success rates
  • Set up alerts for high failure rates
  • Log webhook processing for debugging

Security

  • Use HTTPS endpoints only
  • Implement webhook signature verification
  • Restrict webhook IP addresses if possible
  • Don't expose sensitive data in webhook URLs

Troubleshooting

Webhooks Not Firing

  • Check webhook is enabled for the form
  • Verify form submission is successful
  • Check webhook URL is accessible
  • Review webhook logs for errors

Wrong Data Format

  • Check field name mapping
  • Verify conditional logic isn't filtering fields
  • Test with simple test form first

Authentication Errors

  • Verify API keys/tokens are correct
  • Check header formatting
  • Confirm API permissions

Timeout Issues

  • Optimize webhook endpoint response time
  • Consider asynchronous processing
  • Implement webhook queuing if needed

Rate Limiting

Some APIs have rate limits. For high-volume forms:

  • Implement webhook queuing
  • Use batch processing where possible
  • Consider using integration platforms (Zapier, Make) that handle rate limiting
← Form AnalyticsTroubleshooting →