Webhook Configuration

Learn how to create, configure, and manage webhooks in Pollarix.

Setup Overview

---

Creating a Webhook

1

Access Webhook Settings

Log in to Pollarix dashboard → Department Settings → Webhooks

2

Create New Webhook

Click the 'New Webhook' button to open the configuration form

3

Configure Settings

Enter webhook name, URL, and select events to subscribe

4

Add HTTP Headers

Optional: Add authentication headers for security

5

Test Webhook

Send a test payload to verify your endpoint

6

Save & Activate

Save your webhook - it will be active immediately

---

Configuration Fields

Webhook Name

A descriptive name to identify your webhook:

Example: CRM Sync
Example: Slack Notifications
Example: Survey Completion Notifier

Webhook URL

The HTTPS endpoint where Pollarix will send webhook payloads:

https://your-server.com/webhooks/pollarix
https://api.yourcompany.com/integrations/pollarix

URL Requirements

• Must be a valid URL format
• HTTPS is strongly recommended for production
• The endpoint must be publicly accessible
• Ensure your server can handle POST requests

Events

Select one or more events that will trigger this webhook:

Event	Description	Common Use Cases
SURVEY_COMPLETED	Respondent finishes a survey	Sync to CRM, send alerts
SURVEY_STATUS_CHANGED	Survey status is modified	Update dashboards
COUPON_REDEEMED	Coupon is distributed	Track rewards, inventory

---

HTTP Headers

Add custom headers to authenticate or identify webhook requests.

Secret Token

Recommended for most use cases:

Header Key	Example Value
X-Webhook-Secret	your-random-secret-here

Generate a secure token

openssl rand -hex 32

Bearer Token

For OAuth/JWT authentication:

Header Key	Example Value
Authorization	Bearer your-api-token

API Key

For API key authentication:

Header Key	Example Value
X-API-Key	pk_live_abc123

Custom Headers

Any custom identifier:

Header Key	Example Value
X-Custom-Header	custom-value
X-Source	pollarix

Adding Headers:

1. Expand the HTTP Headers section
2. Click Add to create a new header row
3. Enter the header key and value
4. Repeat for additional headers

Security Best Practice

Always use custom headers or tokens to verify that incoming webhooks are genuinely from Pollarix. See Security Best Practices for more details.

---

Testing Your Webhook

Before saving, test your webhook configuration:

Test Steps

1. Click the Test button
2. Pollarix will send a test payload to your URL
3. Verify your server received the request
4. Check for any error messages

Test Payload Example (click to expand)

{
  "event": "test",
  "timestamp": "2024-01-15T10:30:00Z",
  "webhookId": "wh_test123",
  "departmentId": "dept_xyz789",
  "message": "This is a test webhook from Pollarix",
  "data": {
    "test": true
  }
}

If Test Fails

Issue	Solution
Connection refused	Verify endpoint URL is correct
Timeout	Ensure server is running and publicly accessible
SSL error	Verify SSL certificate is valid
401/403	Check authentication headers

---

Managing Webhooks

Viewing Webhooks

The webhooks list displays:

Column	Description
Name	Webhook identifier
URL	Target endpoint
Status	Active/Inactive indicator
Events	Subscribed event types

Filtering Webhooks

Use the filter buttons to view:

• All - All webhooks
• Active - Only enabled webhooks
• Inactive - Only disabled webhooks

Use the search bar to find webhooks by name or URL.

Editing a Webhook

1. Click the More Actions menu (⋮) on a webhook card
2. Select Edit
3. Modify the configuration
4. Click Save

Enabling/Disabling Webhooks

Toggle the switch on any webhook card to enable or disable it without deleting.

info

Disabled webhooks retain their configuration but won't receive any events.

Deleting a Webhook

1. Click the More Actions menu (⋮)
2. Select Delete
3. Confirm the deletion

Warning

Deleting a webhook is permanent and cannot be undone. Any integrations depending on this webhook will stop receiving events.

---

Webhook Limits

Aspect	Limit
Webhooks per department	Varies by plan
Events per webhook	Unlimited
Custom headers	Unlimited
URL length	2048 characters
Payload timeout	30 seconds

---

Troubleshooting

Webhook Not Receiving Events

1. Check Status: Ensure the webhook is active (toggle is ON)
2. Verify URL: Confirm the endpoint is accessible from the internet
3. Check Events: Verify you've subscribed to the correct events
4. Test Webhook: Use the test feature to debug connectivity
5. Check Server Logs: Review your server logs for incoming requests

Test Webhook Fails

• Verify your endpoint URL is correct
• Ensure your server is running and publicly accessible
• Check firewall rules allow incoming connections
• Verify SSL certificate is valid (for HTTPS)
• Try testing with webhook.site first

Duplicate Events

If you're receiving duplicate events:

• Implement idempotency using the webhookId + timestamp
• Check if multiple webhooks are configured for the same event
• Verify your endpoint returns a 2xx status code promptly

Delayed Events

Webhook delivery may be delayed if:

• Your server is responding slowly (> 5 seconds)
• Previous webhook calls failed and are being retried
• High volume of events in queue

Solution: Ensure your endpoint responds quickly and processes data asynchronously.

---

Next Steps

• Events Reference - Detailed payload documentation
• API Reference - Programmatic webhook management
• Security Best Practices - Secure your webhooks