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

# Lead Events

> Triggered when leads are created, updated, or deleted

## Event Types

* **`lead_created`** - New lead received
* **`lead_updated`** - Lead information changed
* **`lead_deleted`** - Lead archived/deleted

## Webhook Details

**Event IDs**: `lead_created`, `lead_updated`, `lead_deleted`\
**Content-Type**: `application/json`\
**Method**: `POST`

## Authentication

All webhooks include JWT authentication in the Authorization header:

<CodeGroup>
  ```javascript Node.js theme={null}
  const jwt = require('jsonwebtoken');

  app.post('/webhook', (req, res) => {
    const token = req.headers.authorization?.split('Bearer ')[1];
    
    try {
      const decoded = jwt.verify(token, process.env.INTEGRATION_UUID);
      console.log('Event:', decoded.event_id); // 'lead_created'
      console.log('Company:', decoded.company_uuid);
      
      const { lead, configuration } = req.body;
      // Process lead data...
      
      res.status(200).send('OK');
    } catch (error) {
      res.status(401).send('Invalid token');
    }
  });
  ```

  ```python Python theme={null}
  import jwt
  from flask import Flask, request

  app = Flask(__name__)

  @app.route('/webhook', methods=['POST'])
  def webhook():
      token = request.headers.get('Authorization', '').replace('Bearer ', '')
      
      try:
          decoded = jwt.decode(token, os.getenv('INTEGRATION_UUID'), algorithms=['HS256'])
          print(f"Event: {decoded['event_id']}")  # 'lead_created'
          print(f"Company: {decoded['company_uuid']}")
          
          payload = request.json
          lead = payload['lead']
          # Process lead data...
          
          return 'OK', 200
      except jwt.InvalidTokenError:
          return 'Invalid token', 401
  ```
</CodeGroup>

## JWT Token Payload

<ResponseField name="company_uuid" type="string">
  UUID of the company that received the lead
</ResponseField>

<ResponseField name="user_uuid" type="string">
  UUID of the user who created the lead
</ResponseField>

<ResponseField name="event_id" type="string">
  Always `lead_created` for this event
</ResponseField>

<ResponseField name="api_key" type="string">
  Your integration's API key
</ResponseField>

## Webhook Payload Schema

<ResponseField name="lead" type="object">
  The created lead object

  <Expandable title="lead object">
    <ResponseField name="uuid" type="string">
      Unique identifier for the lead
    </ResponseField>

    <ResponseField name="created_at" type="number">
      Unix timestamp when lead was created
    </ResponseField>

    <ResponseField name="updated_at" type="number">
      Unix timestamp when lead was last updated
    </ResponseField>

    <ResponseField name="company_name" type="string">
      Lead company name
    </ResponseField>

    <ResponseField name="email" type="string">
      Lead contact email
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      Lead contact phone number
    </ResponseField>

    <ResponseField name="first_name" type="string">
      Lead contact first name
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Lead contact last name
    </ResponseField>

    <ResponseField name="created_by_user_uuid" type="string">
      UUID of user who created the lead
    </ResponseField>

    <ResponseField name="created_by_user_email" type="string">
      Email of user who created the lead
    </ResponseField>

    <ResponseField name="created_by_user_first_name" type="string">
      First name of user who created the lead
    </ResponseField>

    <ResponseField name="created_by_user_last_name" type="string">
      Last name of user who created the lead
    </ResponseField>

    <ResponseField name="custom_fields" type="array">
      Array of custom field values

      <Expandable title="custom_fields items">
        <ResponseField name="uuid" type="string">
          Custom field UUID
        </ResponseField>

        <ResponseField name="label" type="string">
          Custom field display name
        </ResponseField>

        <ResponseField name="type" type="string">
          Field type: `text`, `textarea`, `number`, `date`, `boolean`, `select`, `multi_select`
        </ResponseField>

        <ResponseField name="value" type="object">
          Field value object with type-specific structure
        </ResponseField>

        <ResponseField name="custom_field_value_uuid" type="string">
          UUID of the field value record
        </ResponseField>

        <ResponseField name="options" type="array">
          Available options for select/multi\_select fields
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tags" type="array">
      Array of tags associated with the lead

      <Expandable title="tags items">
        <ResponseField name="uuid" type="string">
          Tag UUID
        </ResponseField>

        <ResponseField name="label" type="string">
          Tag display name
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="assigned_users" type="array">
      Array of users assigned to the lead

      <Expandable title="assigned_users items">
        <ResponseField name="uuid" type="string">
          User UUID
        </ResponseField>

        <ResponseField name="email" type="string">
          User email
        </ResponseField>

        <ResponseField name="first_name" type="string">
          User first name
        </ResponseField>

        <ResponseField name="last_name" type="string">
          User last name
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="received_from_company" type="array">
      Array of partner companies that sent this lead

      <Expandable title="received_from_company items">
        <ResponseField name="partnership_uuid" type="string">
          Partnership UUID
        </ResponseField>

        <ResponseField name="company_name" type="string">
          Partner company name
        </ResponseField>

        <ResponseField name="company_domain" type="string">
          Partner company domain
        </ResponseField>

        <ResponseField name="sent_date" type="number">
          Unix timestamp when lead was sent
        </ResponseField>

        <ResponseField name="sent_by_user_email" type="string">
          Email of user who sent the lead
        </ResponseField>

        <ResponseField name="sent_by_user_first_name" type="string">
          First name of user who sent the lead
        </ResponseField>

        <ResponseField name="sent_by_user_last_name" type="string">
          Last name of user who sent the lead
        </ResponseField>

        <ResponseField name="partner_type" type="string">
          Type of partnership: `referral` or `reseller`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="sent_to_companies" type="array">
      Array of partner companies this lead was sent to
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="configuration" type="array">
  Integration configuration settings for field mapping

  <Expandable title="configuration items">
    <ResponseField name="id" type="string">
      Configuration section ID (e.g., `lead_integration_settings`)
    </ResponseField>

    <ResponseField name="selected" type="array">
      Selected configuration options

      <Expandable title="selected items">
        <ResponseField name="id" type="string">
          Option ID (e.g., `unique_field_lead`)
        </ResponseField>

        <ResponseField name="value" type="string">
          Selected value (e.g., `email`)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Payload

```json theme={null}
{
  "lead": {
    "uuid": "lead_5336ba48-2ee0-4565-bbf7-f938d51042c1",
    "created_at": 1716214515227,
    "updated_at": 1716214515227,
    "company_name": "Prospect Company Inc",
    "email": "contact@prospect.com",
    "phone_number": "+1-555-123-4567",
    "first_name": "Jane",
    "last_name": "Doe",
    "created_by_user_uuid": "user_12345678-1234-5678-9012-123456789abc",
    "created_by_user_email": "sales@journeybee.io",
    "created_by_user_first_name": "Sales",
    "created_by_user_last_name": "Team",
    "custom_fields": [
      {
        "uuid": "cf_lead_industry",
        "label": "Industry",
        "type": "select",
        "value": { "select": 2 },
        "custom_field_value_uuid": "cfv_industry_tech",
        "options": [
          { "id": 0, "label": "Healthcare" },
          { "id": 1, "label": "Finance" },
          { "id": 2, "label": "Technology" },
          { "id": 3, "label": "Retail" }
        ]
      }
    ],
    "tags": [
      {
        "uuid": "tag_hot_lead",
        "label": "Hot Lead"
      }
    ],
    "assigned_users": [
      {
        "uuid": "user_87654321-4321-8765-2109-876543210987",
        "email": "john.manager@company.com",
        "first_name": "John",
        "last_name": "Manager"
      }
    ],
    "received_from_company": [
      {
        "partnership_uuid": "partnership_12345678-1234-5678-9012-123456789abc",
        "company_name": "TechCorp Solutions",
        "company_domain": "techcorp.com",
        "sent_date": 1716214515227,
        "sent_by_user_email": "partner@techcorp.com",
        "sent_by_user_first_name": "Partner",
        "sent_by_user_last_name": "User",
        "partner_type": "referral"
      }
    ],
    "sent_to_companies": []
  },
  "configuration": [
    {
      "id": "lead_integration_settings",
      "selected": [
        {
          "id": "unique_field_lead",
          "value": "email"
        }
      ]
    }
  ]
}
```

## Notes

* Webhook is sent when a new lead is created in JourneyBee
* JWT token must be verified using your Integration UUID as the secret
* `received_from_company` array indicates if lead came from a partner
* `sent_to_companies` array shows if lead was forwarded to partners
* Custom fields and tags arrays may be empty if none are configured