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, company.deleted
  • Document events: document.uploaded, document.processed, document.deleted
  • Email events: email.created, email.verified
  • AI events: ai.processing_started, ai.processing_completed
  • Contribution events: contribution.created, contribution.updated

​
Quick Start Examples

// 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",
    "partner_id": "partner_67890",
    "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"
  }
}

​
AI Processing Completed Event

{
  "event": "ai.processing_completed",
  "timestamp": "2024-01-15T10:40:00Z",
  "data": {
    "request_id": "ai_request_54321",
    "mode": "EXTRACT_COMPANY_INFO",
    "status": "completed",
    "result": {
      "extracted_data": { ... }
    }
  }
}

​
Security & Validation

  • HTTPS Required: All webhook URLs must use HTTPS
  • 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. Return 200 status codes promptly to acknowledge receipt
  2. Process asynchronously for complex operations
  3. Implement idempotency to handle duplicate events
  4. Validate signatures to ensure authenticity
  5. Log events for debugging and monitoring

​
Next Steps

  1. Create a new document
  2. Get document details
  3. Update an existing document