Webhook Configuration
This guide covers how to set up, configure, and manage webhooks in your Peridio account using both the CLI and web interface.
Prerequisites
Before setting up webhooks, ensure you have:
- An HTTPS endpoint that can receive POST requests
- A Peridio account with appropriate permissions
- The Peridio CLI installed and configured (for CLI usage)
Creating a Webhook
Using the Peridio CLI
The most straightforward way to create a webhook is using the Peridio CLI:
peridio webhooks create --url https://your-domain.com/webhooks
Adding Event Filtering
Specify which events you want to receive using the --enabled-events
flag:
peridio webhooks create \
--url https://your-domain.com/webhooks \
--enabled-events device.connected device.release-changed
Adding a Description
Include a description to help identify the webhook's purpose:
peridio webhooks create \
--url https://your-domain.com/webhooks \
--description "Production webhook for device monitoring" \
--enabled-events device.connected device.authentication-failed
Multiple Events
You can specify multiple events in several ways:
# Using multiple flags
peridio webhooks create \
--url https://your-domain.com/webhooks \
--enabled-events device.connected \
--enabled-events device.release-changed \
--enabled-events device.updated
# Using comma-separated values
peridio webhooks create \
--url https://your-domain.com/webhooks \
--enabled-events device.connected,device.release-changed,device.updated
URL Verification
When creating a webhook, Peridio automatically performs URL verification:
- Test request sent - Peridio sends a
webhook.test_fire
event to your endpoint - Response required - Your endpoint must return a 200 HTTP status code
- Timeout handling - The verification request has a reasonable timeout period
- Failure handling - If verification fails, the webhook creation will fail
Example verification payload:
{
"version": 1,
"prn": "prn:1:organization-id:event:event-id",
"type": "webhook",
"inserted_at": "2023-09-14T20:23:30Z",
"data": {
"type": "test_fire",
"data": {}
}
}
Your endpoint should respond with:
HTTP/1.1 200 OK
Content-Type: application/json
Managing Webhooks
Listing Webhooks
View all webhooks in your account:
peridio webhooks list
Getting Webhook Details
Retrieve information about a specific webhook:
peridio webhooks get --prn prn:1:your-org:webhook:webhook-id
Updating Webhooks
Modify existing webhook configuration:
# Update URL
peridio webhooks update \
--prn prn:1:your-org:webhook:webhook-id \
--url https://new-domain.com/webhooks
# Update enabled events
peridio webhooks update \
--prn prn:1:your-org:webhook:webhook-id \
--enabled-events device.connected,device.release-changed
# Update webhook state
peridio webhooks update \
--prn prn:1:your-org:webhook:webhook-id \
--state disabled
# Update description
peridio webhooks update \
--prn prn:1:your-org:webhook:webhook-id \
--description "Updated webhook for monitoring"
Webhook States
Webhooks can be in different states:
- enabled - Active and receiving events
- disabled - Inactive, not receiving events
Change the state using the --state
parameter when updating.
Secret Management
Understanding Webhook Secrets
Each webhook has an associated secret used for HMAC-SHA256 signature generation:
- Format - 128-bit secrets encoded as uppercase hexadecimal
- Security - Used to verify webhook authenticity
- Rotation - Can be rolled for enhanced security
Rolling Secrets
Update a webhook's secret for security purposes:
peridio webhooks roll-secret --prn prn:1:your-org:webhook:webhook-id
Important considerations:
- Rolling secrets may cause a brief transition period where both old and new secrets are valid
- Update your verification code to handle dual signatures during transitions
- Test your verification logic after rolling secrets
Testing Webhooks
Test Fire
Send a test event to verify your webhook endpoint:
peridio webhooks test-fire --prn prn:1:your-org:webhook:webhook-id
This sends a webhook.test_fire
event to your endpoint, allowing you to:
- Verify your endpoint is reachable
- Test your signature verification logic
- Confirm your event processing works correctly
Testing Your Endpoint
Before creating a webhook, ensure your endpoint:
- Accepts POST requests on your webhook URL
- Returns 200 status for successful processing
- Handles JSON payloads correctly
- Verifies signatures (recommended)
- Processes quickly to avoid timeouts
Example endpoint test:
# Test your endpoint manually
curl -X POST https://your-domain.com/webhooks \
-H "Content-Type: application/json" \
-d '{"test": "data"}'
Event Filtering
Available Events
Configure which events trigger webhook deliveries:
- device.authentication-failed - Device authentication failures
- device.checked-for-release - Device checks for firmware updates
- device.claimed-release - Device claims a firmware release
- device.connected - Device connects to Peridio
- device.release-changed - Device firmware release changes
- device.updated - Device information updates
- api_key.created - API key creation
- webhook.test-fire - Test events (always enabled during verification)
Best Practices
- Subscribe selectively - Only enable events you actually need
- Start small - Begin with a few key events and add more as needed
- Test thoroughly - Use test-fire to validate each event type you enable
- Monitor volume - Be aware of high-frequency events like
device.checked-for-release
Configuration Examples
Basic Device Monitoring
peridio webhooks create \
--url https://monitoring.company.com/peridio-webhooks \
--description "Device monitoring webhook" \
--enabled-events device.connected,device.authentication-failed
Comprehensive Tracking
peridio webhooks create \
--url https://api.company.com/peridio/events \
--description "Full device lifecycle tracking" \
--enabled-events device.connected,device.release-changed,device.updated,device.claimed-release
Security-Focused
peridio webhooks create \
--url https://security.company.com/device-alerts \
--description "Security event monitoring" \
--enabled-events device.authentication-failed,api_key.created
Deleting Webhooks
Remove webhooks that are no longer needed:
peridio webhooks delete --prn prn:1:your-org:webhook:webhook-id
Warning: Deleting a webhook cannot be undone. Ensure you have backups of the configuration if needed.
Next Steps
Once your webhook is configured:
- Implement security - Add signature verification to your endpoint
- Understand events - Learn about event types and payload structures
- Monitor and debug - Set up monitoring and handle common issues
Common Configuration Issues
- URL verification fails - Ensure your endpoint returns 200 and is accessible
- HTTPS required - Webhooks only work with HTTPS URLs
- Timeout issues - Ensure your endpoint responds quickly during verification
- Firewall blocking - Verify Peridio can reach your endpoint from the internet