Webhooks - Well Starter Kit

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.

Create your first Webhook

Start by creating a webhook to receive real-time notifications

How Webhooks Work

Register your endpoint: Create a webhook with your URL and specify which events you want to receive
Receive notifications: Well sends HTTP POST requests to your endpoint when events occur
Process events: Your application processes the webhook payload and takes appropriate action
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

JavaScript
Python
cURL

// 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');
});

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

# 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"
      }
    }
  }'

Webhook Management

Create Webhook

Set up a new webhook endpoint

List Webhooks

View all your configured webhooks

Update Webhook

Modify webhook settings and events

Delete Webhook

Remove webhooks you no longer need

Example Webhook Payloads

Company Created Event

{
  "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

{
  "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

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

Documentation Index

​Getting Started

Create your first Webhook

​How Webhooks Work

​Supported Events

​Quick Start Examples

​Webhook Management