> ## 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.

# Deal Events

> Triggered when deals are created, updated, or deleted

## Webhook Details

**Event IDs**: `deal_created`, `deal_updated`, `deal_deleted`\
**Content-Type**: `application/json`\
**Method**: `POST`

## Event Types

* **`deal_created`** - New deal created
* **`deal_updated`** - Deal information or stage changed
* **`deal_deleted`** - Deal archived/deleted

## 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); // 'deal_created', 'deal_updated', or 'deal_deleted'
      console.log('Company:', decoded.company_uuid);
      
      const { deal, configuration } = req.body;
      // Process deal 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']}")  # 'deal_created', 'deal_updated', or 'deal_deleted'
          print(f"Company: {decoded['company_uuid']}")
          
          payload = request.json
          deal = payload['deal']
          # Process deal 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 created the deal
</ResponseField>

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

<ResponseField name="event_id" type="string">
  Event type: `deal_created`, `deal_updated`, or `deal_deleted`
</ResponseField>

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

## Webhook Payload Schema

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

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

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

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

    <ResponseField name="label" type="string">
      Deal name/title
    </ResponseField>

    <ResponseField name="deal_value" type="number">
      Total deal value
    </ResponseField>

    <ResponseField name="total_commission_value" type="number">
      Total commission amount for this deal
    </ResponseField>

    <ResponseField name="commission_calculation" type="object">
      Commission calculation details

      <Expandable title="commission_calculation object">
        <ResponseField name="type" type="string">
          Commission type: `oneOff` or `recurring`
        </ResponseField>

        <ResponseField name="value" type="string">
          Commission amount as string
        </ResponseField>

        <ResponseField name="option" type="string">
          Calculation method: `percentage` or `fixed`
        </ResponseField>

        <ResponseField name="percentage" type="number">
          Percentage rate (if option is `percentage`)
        </ResponseField>

        <ResponseField name="split" type="object">
          Commission split details (if applicable)
        </ResponseField>

        <ResponseField name="recurring_period" type="string">
          Recurring period (if type is `recurring`)
        </ResponseField>

        <ResponseField name="number_of_occurrences" type="number">
          Number of recurring payments (if applicable)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="currency_code" type="string">
      Three-letter currency code (e.g., `USD`)
    </ResponseField>

    <ResponseField name="currency_label" type="string">
      Human-readable currency name
    </ResponseField>

    <ResponseField name="lead_uuid" type="string">
      UUID of the associated lead
    </ResponseField>

    <ResponseField name="stage_uuid" type="string">
      UUID of the current deal stage
    </ResponseField>

    <ResponseField name="stage_phase" type="string">
      Deal stage phase: `discovery`, `qualification`, `proposal`, `negotiation`, `closed_won`, `closed_lost`
    </ResponseField>

    <ResponseField name="payment_stage_uuid" type="string">
      UUID of the payment stage (if different from main stage)
    </ResponseField>

    <ResponseField name="partnership_uuid" type="string">
      UUID of the associated partnership
    </ResponseField>

    <ResponseField name="partner_company_name" type="string">
      Name of the partner company
    </ResponseField>

    <ResponseField name="partner_company_domain" type="string">
      Email domain of the partner company
    </ResponseField>

    <ResponseField name="deal_owned_by_reseller" type="boolean">
      Whether this deal is owned by a reseller partner
    </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 deal

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

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

        <ResponseField name="background_color" type="string">
          Tag background color (hex code)
        </ResponseField>

        <ResponseField name="text_color" type="string">
          Tag text color (hex code)
        </ResponseField>
      </Expandable>
    </ResponseField>

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

      <Expandable title="assigned_users items">
        <ResponseField name="id" type="number">
          User internal ID
        </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>

        <ResponseField name="profile_image_id" type="number">
          Profile image asset ID
        </ResponseField>

        <ResponseField name="profile_image_uuid" type="string">
          Profile image asset UUID
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="payments" type="array">
      Array of payments associated with the deal

      <Expandable title="payments items">
        <ResponseField name="uuid" type="string">
          Payment UUID
        </ResponseField>

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

        <ResponseField name="payment_date" type="number">
          Unix timestamp of payment date
        </ResponseField>

        <ResponseField name="payment_value" type="number">
          Payment amount
        </ResponseField>

        <ResponseField name="payment_processing" type="boolean">
          Whether payment is currently processing
        </ResponseField>

        <ResponseField name="payment_completed" type="boolean">
          Whether payment has been completed
        </ResponseField>

        <ResponseField name="approved" type="boolean">
          Whether payment has been approved
        </ResponseField>
      </Expandable>
    </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., `deal_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_deal`)
        </ResponseField>

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

## Example Payload

```json theme={null}
{
  "deal": {
    "uuid": "deal_ee436d2b-77a4-4951-9dbf-264ed117ba22",
    "created_at": 1716214515227,
    "updated_at": 1716214515227,
    "label": "Prospect Company - Enterprise Software License",
    "deal_value": 75000,
    "total_commission_value": 7500,
    "commission_calculation": {
      "type": "oneOff",
      "split": null,
      "value": "7500",
      "option": "percentage",
      "percentage": 10,
      "recurring_period": null,
      "number_of_occurrences": null
    },
    "currency_code": "USD",
    "currency_label": "US Dollar",
    "lead_uuid": "lead_5336ba48-2ee0-4565-bbf7-f938d51042c1",
    "stage_uuid": "stage_96cea904-da45-416b-8d5f-f4fbe027a164",
    "stage_phase": "negotiation",
    "payment_stage_uuid": null,
    "partnership_uuid": "partnership_9bb9aa55-6407-482a-9236-f755e72c20e5",
    "partner_company_name": "TechCorp Solutions",
    "partner_company_domain": "techcorp.com",
    "deal_owned_by_reseller": false,
    "custom_fields": [
      {
        "uuid": "cf_deal_priority",
        "label": "Deal Priority",
        "type": "select",
        "value": { "select": 2 },
        "options": [
          { "id": 0, "label": "Low" },
          { "id": 1, "label": "Medium" },
          { "id": 2, "label": "High" },
          { "id": 3, "label": "Critical" }
        ],
        "custom_field_value_uuid": "cfv_priority_high"
      }
    ],
    "tags": [
      {
        "uuid": "tag_enterprise",
        "label": "Enterprise",
        "background_color": "#10B981",
        "text_color": "#FFFFFF"
      }
    ],
    "assigned_users": [
      {
        "id": 456,
        "email": "john.manager@company.com",
        "first_name": "John",
        "last_name": "Manager",
        "profile_image_id": 789,
        "profile_image_uuid": "asset_87654321-4321-8765-2109-876543210987"
      }
    ],
    "payments": []
  },
  "configuration": [
    {
      "id": "deal_integration_settings",
      "selected": [
        {
          "id": "unique_field_deal",
          "value": "label"
        }
      ]
    }
  ]
}
```

## Notes

* Webhooks are sent when deals are created, updated, or deleted in JourneyBee
* JWT token contains the specific event type in the `event_id` field
* JWT token must be verified using your Integration UUID as the secret
* The deal payload structure is the same for all event types
* Commission calculations include both percentage and fixed amount options
* `deal_owned_by_reseller` indicates if a reseller partner owns this deal
* For `deal_created` events, payments array will typically be empty
* For `deal_deleted` events, the deal data represents the final state before deletion