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

# Webhooks

Set up real-time notifications to receive updates from the Well Core API when important events occur in your organization.

## Getting Started

Webhooks allow your application to receive instant notifications when events happen, such as companies being created, documents being uploaded, or AI processing completing.

<Card title="Create your first Webhook" icon="webhook" iconType="duotone" href="/api-reference/endpoint/webhooks/create">
  Start by creating a webhook to receive real-time notifications
</Card>

## How Webhooks Work

1. **Register your endpoint**: Create a webhook with your URL and specify which events you want to receive
2. **Receive notifications**: Well sends HTTP POST requests to your endpoint when events occur
3. **Process events**: Your application processes the webhook payload and takes appropriate action
4. **Respond with 200**: Return a 200 status code to acknowledge receipt

## Supported Events

The Well Core API supports webhooks for various resource events:

* **Company events**: `company.created`, `company.updated`
* **Document events**: `document.uploaded`, `document.processed`
* **People events**: `people.created`, `people.updated`
* **Invoice events**: `invoice.created`, `invoice.updated`

## Quick Start Examples

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    // Create a webhook
    const webhookResponse = await fetch('https://api.well.com/v1/webhooks', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
      },
      body: JSON.stringify({
        data: {
          type: 'webhook',
          attributes: {
            url: 'https://your-app.com/webhook',
            events: ['company.created', 'document.uploaded'],
            description: 'Main webhook for production'
          }
        }
      })
    });

    // Handle webhook in your app (Express.js example)
    app.post('/webhook', (req, res) => {
      const { event, data } = req.body;

      switch (event) {
        case 'company.created':
          console.log('New company created:', data.company_id);
          break;
        case 'document.uploaded':
          console.log('Document uploaded:', data.document_id);
          break;
      }

      res.status(200).send('OK');
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests
    from flask import Flask, request

    # Create a webhook
    webhook_response = requests.post('https://api.well.com/v1/webhooks',
      headers={'Authorization': f'Bearer {api_key}'},
      json={
        'data': {
          'type': 'webhook',
          'attributes': {
            'url': 'https://your-app.com/webhook',
            'events': ['company.created', 'document.uploaded'],
            'description': 'Main webhook for production'
          }
        }
      }
    )

    # Handle webhook in your app (Flask example)
    app = Flask(__name__)

    @app.route('/webhook', methods=['POST'])
    def handle_webhook():
        data = request.json
        event = data.get('event')
        payload = data.get('data')

        if event == 'company.created':
            print(f"New company created: {payload['company_id']}")
        elif event == 'document.uploaded':
            print(f"Document uploaded: {payload['document_id']}")

        return 'OK', 200
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    # Create a webhook
    curl -X POST https://api.well.com/v1/webhooks \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "data": {
          "type": "webhook",
          "attributes": {
            "url": "https://your-app.com/webhook",
            "events": ["company.created", "document.uploaded"],
            "description": "Main webhook for production"
          }
        }
      }'
    ```
  </Tab>
</Tabs>

## Webhook Management

<CardGroup cols={2}>
  <Card title="Create Webhook" icon="plus" iconType="duotone" href="/api-reference/endpoint/webhooks/create">
    Set up a new webhook endpoint
  </Card>

  <Card title="List Webhooks" icon="list" iconType="duotone" href="/api-reference/endpoint/webhooks/get-all">
    View all your configured webhooks
  </Card>

  <Card title="Update Webhook" icon="pen-to-square" iconType="duotone" href="/api-reference/endpoint/webhooks/update">
    Modify webhook settings and events
  </Card>

  <Card title="Delete Webhook" icon="trash" iconType="duotone" href="/api-reference/endpoint/webhooks/delete">
    Remove webhooks you no longer need
  </Card>
</CardGroup>

## Example Webhook Payloads

### Company Created Event

```json theme={null}
{
  "event": "company.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "company_id": "comp_12345",
    "name": "Acme Corp",
    "description": "Leading technology company",
    "external_workspace_id": "external workspace id (UUID)",

    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### Document Uploaded Event

```json theme={null}
{
  "event": "document.uploaded",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "document_id": "doc_98765",
    "name": "Important Document.pdf",
    "size": 1048576,
    "organisation_id": "org_11111",
    "uploaded_at": "2024-01-15T10:35:00Z"
  }
}
```

## Security & Validation

* **Timeout**: Webhook requests timeout after 10 seconds
* **Retries**: Failed webhooks are retried up to 3 times with exponential backoff
* **Headers**: Each webhook includes a `X-Well-Signature` header for verification

## Best Practices

1. **Use HTTP status codes** to indicate success or failure
2. **Use JSON:API standard** for request and response formats