Skip to main content
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

  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

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

​
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

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