What Are Webhooks?
Webhooks are automated HTTP requests that Peanuts sends to your specified URL whenever certain events occur. Think of them as real-time notifications that carry your data to other systems.Real-Time Delivery
Data is sent immediately when entries are created - no polling required
Universal Compatibility
Connect to Zapier, Make, n8n, or any webhook-compatible service
Secure Signatures
Optional HMAC signatures verify that requests come from Peanuts
Delivery Tracking
View delivery history with status codes and error messages
Setting Up a Webhook
1
Open Integrations
Navigate to your helper and tap the Settings (gear) icon, then scroll to Integrations.
2
Expand Webhook Settings
Tap the Outgoing Webhook accordion to reveal the configuration options.
3
Enable Webhook
Toggle Enable webhook to activate webhook delivery for this helper.
4
Enter Webhook URL
Paste the URL where you want to receive the webhook POST requests.Examples:
https://hooks.zapier.com/hooks/catch/123456/abcdefhttps://hook.us1.make.com/abc123xyzhttps://n8n.yourserver.com/webhook/peanutshttps://api.yourapp.com/webhooks/peanuts
5
Test the Connection
Click the Test button (flask icon) to send a test payload and verify your endpoint is receiving data correctly.
6
Save Configuration
Tap Save to apply the webhook configuration.

Webhook Payload Format
Every webhook request is a POST request with a JSON body containing event details:Payload Fields
| Field | Type | Description |
|---|---|---|
event | string | Event type: entry.created, entry.updated, or entry.deleted |
timestamp | string | ISO 8601 timestamp when the webhook was sent |
helper.id | string | Unique identifier (UUID) of the helper |
helper.name | string | Display name of the helper |
helper.command | string | Telegram command for the helper |
entry.id | string | Unique identifier (UUID) of the entry |
entry.data | object | All field values from the entry |
entry.created_at | string | When the entry was originally created |
HTTP Headers
Every webhook request includes these headers:| Header | Description |
|---|---|
Content-Type | Always application/json |
User-Agent | Identifies the request as coming from Peanuts |
X-Peanuts-Signature | HMAC-SHA256 signature (only if signing secret is set) |
Signing Secret (Security)
For production use, we strongly recommend adding a Signing Secret to verify that webhook requests genuinely come from Peanuts. Create a random string (32+ characters recommended). You can use a password generator or run:X-Peanuts-Signature header matches the expected signature.
Signature Verification Examples
Delivery History
Peanuts tracks every webhook delivery attempt so you can monitor and troubleshoot issues.Delivery Statuses
| Status | Icon | Description |
|---|---|---|
| Success | ✓ Green | Webhook was delivered and your server responded with 2xx status |
| Failed | ✕ Red | Delivery failed - check the error message for details |
| Pending | ○ Yellow | Delivery is in progress (rare, usually resolves quickly) |
Popular Integrations
- Create a new Zap and choose Webhooks by Zapier as the trigger
- Select Catch Hook as the trigger event
- Copy the webhook URL provided by Zapier
- Paste it into your Peanuts webhook configuration
- Send a test from Peanuts to set up your Zap fields
- Add any actions you want (Google Sheets, Slack, Email, etc.)
- Create a new Scenario
- Add a Webhooks module as the first step
- Choose Custom webhook
- Copy the webhook URL
- Paste it into Peanuts and send a test
- Make will auto-detect your data structure
- Add a Webhook node to your workflow
- Set the HTTP Method to POST
- Copy the Production or Test webhook URL
- Configure it in Peanuts
- Use the Listen for Test Event to verify the connection
- Open your Google Sheet and go to Extensions → Apps Script
- Deploy a web app that receives POST requests:
- Deploy as web app and use the URL in Peanuts
- Create a Slack App at api.slack.com
- Enable Incoming Webhooks
- Create a webhook for your channel
- Use a middleware service (Zapier/Make) to transform Peanuts data to Slack format
Best Practices
Only use HTTPS URLs for webhooks to ensure data is encrypted in transit Respond with 200 status code as fast as possible - do heavy processing asynchronously Always configure a signing secret for production to prevent spoofed requests Use the entry ID to detect and handle potential duplicate deliveries gracefullyTroubleshooting
Common causes:- Your server returned a non-2xx status code
- The URL is unreachable (firewall, DNS, or server down)
- Request timed out (server took too long to respond)
- Check your server logs for errors
- Verify the URL is accessible from the internet
- Ensure your server responds within 30 seconds
- Check if your firewall allows requests from Peanuts
- Your server accepts POST requests from any origin
- No IP-based restrictions blocking Peanuts servers
- The URL is publicly accessible (not localhost)
- Secret mismatch between Peanuts and your server
- Payload is being modified before verification (parsed twice, whitespace changes)
- Using wrong hashing algorithm (should be HMAC-SHA256)
- Log the raw signature header you receive
- Log the signature you compute
- Ensure you’re using the raw JSON string, not a re-serialized object
- The webhook is enabled in settings
- A valid URL is configured
- An entry is created (updates/deletes coming soon)
Technical Specifications
Webhooks are processed asynchronously and do not block entry creation. If a webhook fails, your entry is still saved successfully.Request Details
| Property | Value |
|---|---|
| HTTP Method | POST |
| Content-Type | application/json |
| Timeout | 30 seconds |
| Retry Policy | No automatic retries (currently) |
| Max Payload Size | ~100KB |
Response Expectations
Your endpoint should:- Return a 2xx status code (200, 201, 202, 204) for success
- Respond within 30 seconds
- Handle the JSON body appropriately
Credit Usage
Webhooks are included with all plans at no additional credit cost. There are no per-webhook charges.Related
Get entries delivered directly to your inbox Generate and schedule PDF reportsRequired Screenshots
| Path | Description |
|---|---|
/images/integrations/webhook-setup.png | Webhook configuration interface showing URL field, secret field, and test button |
/images/integrations/webhook-history.png | Delivery history panel showing success/failed deliveries with timestamps |
Key Fixes Applied
- No 4-space indentation - All content starts at column 0 to prevent accidental code blocks
- Proper Mintlify components -
,,,,,,,,,,,, “ all properly closed - Clean Markdown tables - Tables have no leading whitespace and use backticks for field names
- Code fences at column 0 - All code blocks start flush left
- Proper list formatting - Using standard Markdown numbered lists inside accordions

