Complete Guide to Webhooks in Zapforms

# Complete Guide to Webhooks in Zapforms

Webhooks allow you to receive real-time notifications when events happen in your forms. This guide covers everything you need to know about setting up and using webhooks in Zapforms.

## What are Webhooks?

Webhooks are HTTP callbacks that send data to your server when specific events occur. Instead of polling our API for changes, webhooks push data to you instantly.

## Setting Up Webhooks

### 1. Configure Your Endpoint

First, create an endpoint on your server to receive webhook events:

```javascript
// Express.js example
app.post('/webhooks/zapforms', (req, res) => {
const event = req.body;

// Process the event
console.log('Received event:', event);

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

### 2. Add Webhook URL in Dashboard

1. Navigate to your form settings
2. Click on "Webhooks" tab
3. Enter your endpoint URL
4. Select events to subscribe to
5. Save your configuration

## Webhook Events

Currently supported events:

- **submission.created**: New form submission received
- **submission.updated**: Submission data modified
- **submission.deleted**: Submission removed

## Webhook Payload

Each webhook delivers a JSON payload with this structure:

```json
{
"event": "submission.created",
"timestamp": "2025-01-15T10:30:00Z",
"form": {
"id": "form_123abc",
"name": "Contact Form"
},
"submission": {
"id": "sub_456def",
"data": {
"name": "John Doe",
"email": "john@example.com"
},
"metadata": {
"ip": "192.0.2.1",
"submittedAt": "2025-01-15T10:30:00Z"
}
}
}
```

## Verifying Webhook Signatures

For security, verify that webhooks are coming from Zapforms:

```javascript
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
const hash = crypto
.createHmac('sha256', secret)
.update(JSON.stringify(payload))
.digest('hex');

return hash === signature;
}

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

if (!verifyWebhookSignature(req.body, signature, WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}

// Process verified webhook
processWebhook(req.body);
res.status(200).send('OK');
});
```

## Retry Logic

If your endpoint doesn't return a 2xx status code, we'll retry the webhook:

- **Retry attempts**: 3 times
- **Retry delays**: 1 minute, 5 minutes, 30 minutes
- **Timeout**: 30 seconds per request

## Best Practices

1. **Return quickly**: Process webhooks asynchronously to avoid timeouts
2. **Verify signatures**: Always verify webhook authenticity
3. **Handle duplicates**: Use event IDs to prevent duplicate processing
4. **Log everything**: Keep webhook logs for debugging
5. **Monitor failures**: Set up alerts for webhook failures

## Testing Webhooks

Use our webhook testing tool in the dashboard to send test events to your endpoint. You can also use tools like ngrok for local development.

## Troubleshooting

Common issues and solutions:

- **Not receiving webhooks**: Check your firewall and ensure your endpoint is publicly accessible
- **Invalid signature errors**: Verify you're using the correct webhook secret
- **Timeouts**: Process webhooks asynchronously and return 200 immediately
- **Duplicate events**: Implement idempotency using event IDs

## Need Help?

Check our [API documentation](/docs/api) or reach out to [support@zapforms.io](mailto:support@zapforms.io).