Heffl Public API

Integrate Heffl into your workflows with our powerful REST API. Manage clients, create quotes, send invoices, and automate your business operations.

Heffl API

Quick Start

Authentication

To use the Heffl API, authenticate using your API key. Get your API key from your Heffl dashboard settings.

API keys start with heffl_user_

{
  "method": "GET",
  "url": "https://api.heffl.com/api/v1/clients",
  "headers": {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY_HERE"
  }
}

Endpoint

All API requests should be made to:

https://api.heffl.com/api/v1

Rate Limiting

To ensure fair usage and system stability, the API enforces rate limits:

Rate Limit: 60 requests per 60 minutes

If you exceed this limit, you'll receive a 429 Too Many Requests error until your quota resets.

Need Help?

If you encounter any issues while using the Heffl API, please contact our support team.

[email protected]heffl.com/support

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your Heffl workspace. Subscribe to specific events and receive JSON payloads at your webhook URL.

Webhook Structure

Every webhook payload follows a consistent structure with three main fields:

{
  "event": "client.created",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "payload": {
    "id": "clt_123456789",
    "name": "John Doe",
    "email": "[email protected]",
    // ... event-specific data
  }
}

event

The name of the webhook event

timestamp

ISO 8601 timestamp when the event occurred

data

The event payload with resource details

Setting up Webhooks

1.Configure webhook endpoints in Settings → Developers → Webhooks
2.Select events to subscribe to
3.Provide your webhook URL
4.Verify using signature header

Lead Created

Triggered when a new lead is created

lead.created
Example Payload
{
  "id": "lead_123e4567-e89b-12d3-a456-426614174000",
  "name": "John Doe",
  "mobile": "+1234567890",
  "email": "[email protected]",
  "secondaryMobile": null,
  "title": "Marketing Manager",
  "value": 5000,
  "source": "Website",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "website": "https://example.com",
  "archived": false,
  "stage": "New",
  "customFields": {}
}
leads

Lead Updated

Triggered when a lead is updated

lead.updated
Example Payload
{
  "id": "lead_123e4567-e89b-12d3-a456-426614174000",
  "name": "John Doe",
  "mobile": "+1234567890",
  "email": "[email protected]",
  "secondaryMobile": "+0987654321",
  "title": "VP of Marketing",
  "value": 7500,
  "source": "Website",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "website": "https://example.com",
  "archived": false,
  "stage": "Contacted",
  "customFields": {}
}
leads

Lead Stage Changed

Triggered when a lead's stage is changed

lead.stageChanged
Example Payload
{
  "id": "lead_123e4567-e89b-12d3-a456-426614174000",
  "name": "John Doe",
  "mobile": "+1234567890",
  "email": "[email protected]",
  "title": "Marketing Manager",
  "value": 5000,
  "source": "Website",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "website": "https://example.com",
  "archived": false,
  "customFields": {},
  "stage": "Contacted"
}
leads

Lead Deleted

Triggered when a lead is deleted

lead.deleted
Example Payload
{
  "ids": [
    "lead_123e4567-e89b-12d3-a456-426614174000"
  ]
}
leads

Deal Created

Triggered when a new deal is created

deal.created
Example Payload
{
  "id": "deal_123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "title": "Website Redesign Project",
  "price": 5000,
  "expectedCloseDate": "2024-02-15",
  "source": "Website",
  "client": {
    "id": "client_123e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Corporation",
    "number": "CLI-001",
    "taxNumber": "TAX123456",
    "website": "https://acme.com",
    "customFields": {}
  },
  "stage": "Proposal",
  "status": "open",
  "number": "DL-2024-001"
}
deals

Deal Updated

Triggered when a deal is updated

deal.updated
Example Payload
{
  "id": "deal_123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "title": "Website Redesign Project",
  "price": 5500,
  "expectedCloseDate": "2024-02-20",
  "source": "Website",
  "client": {
    "id": "client_123e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Corporation",
    "number": "CLI-001",
    "taxNumber": "TAX123456",
    "website": "https://acme.com",
    "customFields": {}
  },
  "stage": "Negotiation",
  "status": "open",
  "number": "DL-2024-001"
}
deals

Deal Deleted

Triggered when a deal is deleted

deal.deleted
Example Payload
{
  "ids": [
    "deal_123e4567-e89b-12d3-a456-426614174000"
  ]
}
deals

Client Created

Triggered when a new client is created

client.created
Example Payload
{
  "id": "client_123e4567-e89b-12d3-a456-426614174000",
  "name": "Acme Corporation",
  "number": "CLI-001",
  "taxNumber": "TAX123456",
  "website": "https://acme.com",
  "customFields": {}
}
clients

Client Updated

Triggered when a client is updated

client.updated
Example Payload
{
  "id": "client_123e4567-e89b-12d3-a456-426614174000",
  "name": "Acme Corporation Inc.",
  "number": "CLI-001",
  "taxNumber": "TAX123456789",
  "website": "https://acme.com",
  "customFields": {}
}
clients

Client Deleted

Triggered when a client is deleted

client.deleted
Example Payload
{
  "ids": [
    "client_123e4567-e89b-12d3-a456-426614174000"
  ]
}
clients

Contact Created

Triggered when a new contact is created

contact.created
Example Payload
{
  "id": "contact_123e4567-e89b-12d3-a456-426614174000",
  "name": "Jane Smith",
  "firstName": "Jane",
  "lastName": "Smith",
  "mobile": "+1234567890",
  "email": "[email protected]",
  "jobTitle": "Marketing Director",
  "customFields": {}
}
contacts

Contact Updated

Triggered when a contact is updated

contact.updated
Example Payload
{
  "id": "contact_123e4567-e89b-12d3-a456-426614174000",
  "name": "Jane Smith",
  "firstName": "Jane",
  "lastName": "Smith",
  "mobile": "+1234567890",
  "email": "[email protected]",
  "jobTitle": "VP of Marketing",
  "customFields": {}
}
contacts

Contact Deleted

Triggered when a contact is deleted

contact.deleted
Example Payload
{
  "ids": [
    "contact_123e4567-e89b-12d3-a456-426614174000"
  ]
}
contacts

Security & Verification

All webhook requests include a signature header:

x-heffl-signature: sha256=abc123...

Verify the signature using your webhook secret key to ensure the request is legitimate.

whatsapp