# Test Webhook Endpoints

Before relying on webhooks in production, test them to ensure proper configuration and endpoint functionality. DNSRadar provides a testing endpoint that sends a fake event to your webhook.

## Testing a Webhook

Send a POST request to `/webhooks/{uuid}/test`:

```
POST https://api.dnsradar.dev/webhooks/wh_abc123/test
```

The API immediately returns HTTP 202 Accepted, and the test payload is sent to your webhook asynchronously.

## Test Payload

The test endpoint sends a sample DNS change event:

```json
{
  "uuid": "req_test_abc123...",
  "webhook_uuid": "wh_test_abc123...",
  "created": "2026-01-08T10:35:22Z",
  "event": {
    "event_uuid": "evt_test_xyz789",
    "monitor_uuid": "mon_abc123",
    "domain": "piedpiper.com",
    "subdomain": "www",
    "record_type": "A",
    "expected_value": ["1.2.3.4"],
    "previous_value": ["1.2.3.4"],
    "current_value": ["5.6.7.8"],
    "old_state": "VALID",
    "new_state": "MISMATCH",
    "occurred": "2026-01-08T10:35:22Z",
    "incidence_count": 1
  }
}
```

> ℹ️ **INFO:** **Test Identifiers**: Test events use UUIDs prefixed with `_test_` to help you distinguish them from real events.

## Rate Limits

To prevent abuse, the test endpoint has strict rate limits:

- **5 requests per minute** per webhook
- **20 requests per hour** per webhook

> ⚠️ **WARNING:** **Rate Limiting**: Exceeding these limits returns HTTP 429 Too Many Requests. Space out your tests appropriately.

## Response Codes

| Status | Meaning |
|--------|---------|
| 202 Accepted | Test payload queued for delivery |
| 401 Unauthorized | Invalid API key |
| 404 Not Found | Webhook doesn't exist |
| 429 Too Many Requests | Rate limit exceeded |


## Testing Checklist

Before deploying webhooks to production:

- [ ] Webhook endpoint is accessible from the internet
- [ ] HTTPS is configured properly (valid SSL certificate)
- [ ] Authentication headers are validated
- [ ] Endpoint returns 2xx status codes for successful processing
- [ ] Endpoint responds within 30 seconds
- [ ] Error handling is implemented
- [ ] Rate limiting won't cause issues
- [ ] Payload validation is working
- [ ] Test event was received successfully


## Common Testing Issues

### Endpoint Not Receiving Test Events

**Possible causes:**
1. Firewall blocking requests
2. Incorrect URL
3. Server not running
4. HTTPS certificate issues

**Solution:**
```bash
# Test endpoint accessibility
curl -X POST https://your-endpoint.com/webhooks/dnsradar \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'
```

### Endpoint Returns Errors

**Check:**
1. Authentication header validation
2. Payload structure expectations
3. Server logs for errors

**Debug:**

```javascript
app.post('/webhooks/dnsradar', (req, res) => {
  // Log everything during debugging
  console.log('Headers:', req.headers)
  console.log('Body:', req.body)
  console.log('Method:', req.method)

  // Return detailed error info
  try {
    processWebhook(req.body)
    res.status(200).send('OK')
  } catch (error) {
    console.error('Error:', error)
    res.status(500).json({
      error: error.message,
      stack: error.stack
    })
  }
})
```

## Testing Tools

### cURL

```bash
# Test your endpoint directly
curl -X POST https://your-app.com/webhooks/dnsradar \
  -H "X-Webhook-Secret: your-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "event_uuid": "evt_test_manual",
    "monitor_uuid": "mon_test_manual",
    "domain": "test.com",
    "record_type": "A",
    "new_state": "MISMATCH",
    "occurred": "2026-01-08T12:00:00Z"
  }'
```

### Webhook.site

Use [webhook.site](https://webhook.site) to inspect webhook payloads:

```
POST https://api.dnsradar.dev/webhooks

url: https://webhook.site/YOUR-UNIQUE-URL
  method: POST
```

Then test it:

```
POST https://api.dnsradar.dev/webhooks/wh_abc123/test
```

Visit [webhook.site](https://webhook.site) to see the payload.

### Ngrok

Test local endpoints:

```bash
# Expose local server
ngrok http 3000

# Use ngrok URL in webhook
curl -X POST https://api.dnsradar.dev/webhooks \
  -H "X-API-Key: $API_KEY" \
  -d '{"url": "https://abc123.ngrok.io/webhooks/dnsradar", "method": "POST"}'
```

## Next Steps

- [View Webhook Request History](/docs/webhook-requests)
- [Enable/Disable Webhooks](/docs/enable-disable-webhooks)
- [Understand Webhook Retries](/docs/webhook-retries)