> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peanutsapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Send data to external services when entries are added or modified

## What are Webhooks?

Webhooks allow Peanuts to automatically send data to external services whenever entries are added, updated, or deleted in your Helpers. This enables powerful integrations with your existing tools and workflows.

<Info>
  Webhooks are available on **Starter**, **Pro**, and **Team** plans.
</Info>

## How Webhooks Work

<Steps>
  <Step title="Configure a webhook URL">
    Add the endpoint URL where you want data sent
  </Step>

  <Step title="Choose trigger events">
    Select which events trigger the webhook (create, update, delete)
  </Step>

  <Step title="Entry is added/modified">
    When an entry matches the trigger, a webhook fires
  </Step>

  <Step title="Data is sent">
    Entry data is POSTed to your endpoint in JSON format
  </Step>
</Steps>

## Setting Up Webhooks

### Per-Helper Webhook

1. Open Helper → Settings
2. Go to **Integrations → Webhooks**
3. Tap **Add Webhook**
4. Configure:
   * URL endpoint
   * Events to trigger (create, update, delete, all)
   * Optional headers (for authentication)
5. Save and test

### Webhook Payload

When triggered, Peanuts sends a POST request with:

```json theme={null}
{
  "event": "entry.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "helper": {
    "id": "abc123",
    "name": "Expense Tracker"
  },
  "entry": {
    "id": "xyz789",
    "created_at": "2024-01-15T10:30:00Z",
    "data": {
      "amount": 45.00,
      "category": "Food",
      "description": "Lunch at restaurant",
      "date": "2024-01-15"
    }
  }
}
```

## Authentication

### Header Authentication

Add custom headers for API key authentication:

```
Authorization: Bearer your-api-key
X-Custom-Header: your-value
```

### Webhook Signing

Peanuts signs each webhook request with a secret:

* Header: `X-Peanuts-Signature`
* Algorithm: HMAC-SHA256
* Verify to ensure requests are from Peanuts

## Use Cases

<AccordionGroup>
  <Accordion title="Zapier/Make Integration">
    Send entries to Zapier or Make.com to trigger automation workflows.
  </Accordion>

  <Accordion title="Spreadsheet Sync">
    Automatically add entries to Google Sheets or Airtable.
  </Accordion>

  <Accordion title="Accounting Software">
    Push expenses to QuickBooks, Xero, or other accounting tools.
  </Accordion>

  <Accordion title="CRM Updates">
    Update leads or contacts in Salesforce, HubSpot when entries change.
  </Accordion>

  <Accordion title="Custom Applications">
    Send data to your own backend systems for custom processing.
  </Accordion>
</AccordionGroup>

## Webhook Management

### View Delivery History

1. Open Helper → Settings → Webhooks
2. Select a webhook
3. View **Delivery Log**
4. See status, response codes, and errors

### Retry Failed Webhooks

Failed webhooks are automatically retried:

* 1st retry: 1 minute after failure
* 2nd retry: 5 minutes after
* 3rd retry: 30 minutes after
* After 3 failures: Marked as failed, no more retries

### Disable Webhook

1. Open webhook settings
2. Toggle **Enabled** off
3. Webhook stops firing but configuration is saved

## Best Practices

<CardGroup cols={2}>
  <Card title="Use HTTPS" icon="lock">
    Always use HTTPS endpoints for security
  </Card>

  <Card title="Handle Retries" icon="rotate">
    Design your endpoint to handle duplicate deliveries
  </Card>

  <Card title="Respond Quickly" icon="bolt">
    Return 200 within 5 seconds to avoid timeouts
  </Card>

  <Card title="Verify Signatures" icon="shield-check">
    Validate webhook signatures to prevent spoofing
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhook not firing">
    * Check webhook is enabled
    * Verify the trigger events match your action
    * Check delivery log for errors
  </Accordion>

  <Accordion title="Receiving 401/403 errors">
    * Check authentication headers
    * Verify API key is valid
    * Ensure endpoint allows POST requests
  </Accordion>

  <Accordion title="Missing data in payload">
    * All entry fields are included by default
    * Check if field values are null
    * Verify the entry was saved correctly
  </Accordion>
</AccordionGroup>

## Related Features

<CardGroup cols={2}>
  <Card title="Telegram Integration" icon="paper-plane" href="/integrations/telegram">
    Two-way integration via Telegram bot
  </Card>

  <Card title="API Reference" icon="code" href="/api/introduction">
    Direct API access for custom integrations
  </Card>
</CardGroup>