API Reference/Documentation
GitHubDashboard
Reference

Events

Canonical webhook event catalog for the Leadron API, including event names, descriptions, and real payload shapes.

Event-first docs

Canonical list of all webhook event types

Signature verification

Validate every delivery with X-Leadron-Signature

Delivery reliability

Design handlers for retries and idempotency

Webhook Payload Shape

All webhook deliveries use the same envelope. The data object varies by event type.

Webhook envelope
json
1
2
3
4
5
6
7
8
9
10
{
  "id": "evt_01HZXN8Y9K0M7R6Q5P4N3T2S1A",
  "type": "lead.created",
  "createdAt": "2026-05-27T23:34:12.000Z",
  "data": {
    "leadId": "ld_123",
    "email": "jane@acme.com",
    "source": "web_form"
  }
}

Signature verification

Validate every delivery using the X-Leadron-Signature header before processing event payloads.

Catalog Endpoint

Headers

ParameterTypeDescription
X-API-Keyreq
stringTenant API key
Request
HTTP
http
GET https://api.leadron.io/v1/integrations/webhooks/catalog
X-API-Key: ldr_live_sk_a1b2c3d4e5f6g7h8i9j0
Response200OK
200 Response
json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
{
  "success": true,
  "status": 200,
  "message": "Webhook event catalog",
  "data": {
    "leads": [
      {
        "event": "lead.created",
        "description": "Fired when a new lead is created",
        "examplePayload": {
          "leadId": "ld_123",
          "email": "jane@acme.com",
          "source": "web_form"
        }
      },
      {
        "event": "lead.updated",
        "description": "Fired when lead fields are modified",
        "examplePayload": {
          "leadId": "ld_123",
          "changes": {
            "status": "qualified"
          }
        }
      },
      {
        "event": "lead.deleted",
        "description": "Fired when a lead is removed",
        "examplePayload": {
          "leadId": "ld_123"
        }
      }
    ],
    "opportunities": [
      {
        "event": "opportunity.created",
        "description": "New opportunity opened",
        "examplePayload": {
          "opportunityId": "opp_456",
          "value": 25000,
          "stage": "discovery"
        }
      },
      {
        "event": "opportunity.stage_changed",
        "description": "Opportunity moved to a new stage",
        "examplePayload": {
          "opportunityId": "opp_456",
          "from": "discovery",
          "to": "proposal"
        }
      },
      {
        "event": "opportunity.won",
        "description": "Deal marked as won",
        "examplePayload": {
          "opportunityId": "opp_456",
          "value": 25000
        }
      },
      {
        "event": "opportunity.lost",
        "description": "Deal marked as lost",
        "examplePayload": {
          "opportunityId": "opp_456",
          "reason": "budget"
        }
      }
    ],
    "partners": [
      {
        "event": "partner.registered",
        "description": "New partner registered",
        "examplePayload": {
          "partnerId": "ptr_789",
          "company": "Partner Co"
        }
      },
      {
        "event": "partner.approved",
        "description": "Partner approved for program",
        "examplePayload": {
          "partnerId": "ptr_789"
        }
      }
    ],
    "commissions": [
      {
        "event": "commission.earned",
        "description": "Commission recorded",
        "examplePayload": {
          "commissionId": "com_101",
          "amount": 500,
          "partnerId": "ptr_789"
        }
      },
      {
        "event": "commission.paid",
        "description": "Commission paid out",
        "examplePayload": {
          "commissionId": "com_101",
          "amount": 500
        }
      }
    ],
    "tasks": [
      {
        "event": "task.created",
        "description": "New task assigned",
        "examplePayload": {
          "taskId": "tsk_202",
          "title": "Follow up with lead",
          "assigneeId": "usr_303"
        }
      },
      {
        "event": "task.completed",
        "description": "Task marked complete",
        "examplePayload": {
          "taskId": "tsk_202"
        }
      }
    ],
    "forms": [
      {
        "event": "form.submitted",
        "description": "Form submission received",
        "examplePayload": {
          "formId": "frm_404",
          "leadId": "ld_123",
          "fields": {
            "name": "Jane",
            "email": "jane@acme.com"
          }
        }
      }
    ]
  },
  "meta": {
    "timestamp": "2026-05-27T23:34:12.000Z",
    "version": "v1"
  }
}

Event Catalog

Event names and example payload shapes are sourced from the integrations webhook catalog.

Leads

3 events
lead.createdFired when a new lead is created
lead.created payload
json
1
2
3
4
5
6
7
8
9
10
{
  "id": "evt_01HZXN8Y9K0M7R6Q5P4N3T2S1A",
  "type": "lead.created",
  "createdAt": "2026-05-27T23:34:12.000Z",
  "data": {
    "leadId": "ld_123",
    "email": "jane@acme.com",
    "source": "web_form"
  }
}
lead.updatedFired when lead fields are modified
lead.updated payload
json
1
2
3
4
5
6
7
8
9
10
11
{
  "id": "evt_01HZXN8Y9K0M7R6Q5P4N3T2S1A",
  "type": "lead.updated",
  "createdAt": "2026-05-27T23:34:12.000Z",
  "data": {
    "leadId": "ld_123",
    "changes": {
      "status": "qualified"
    }
  }
}
lead.deletedFired when a lead is removed
lead.deleted payload
json
1
2
3
4
5
6
7
8
{
  "id": "evt_01HZXN8Y9K0M7R6Q5P4N3T2S1A",
  "type": "lead.deleted",
  "createdAt": "2026-05-27T23:34:12.000Z",
  "data": {
    "leadId": "ld_123"
  }
}

Opportunities

4 events
opportunity.createdNew opportunity opened
opportunity.created payload
json
1
2
3
4
5
6
7
8
9
10
{
  "id": "evt_01HZXN8Y9K0M7R6Q5P4N3T2S1A",
  "type": "opportunity.created",
  "createdAt": "2026-05-27T23:34:12.000Z",
  "data": {
    "opportunityId": "opp_456",
    "value": 25000,
    "stage": "discovery"
  }
}
opportunity.stage_changedOpportunity moved to a new stage
opportunity.stage_changed payload
json
1
2
3
4
5
6
7
8
9
10
{
  "id": "evt_01HZXN8Y9K0M7R6Q5P4N3T2S1A",
  "type": "opportunity.stage_changed",
  "createdAt": "2026-05-27T23:34:12.000Z",
  "data": {
    "opportunityId": "opp_456",
    "from": "discovery",
    "to": "proposal"
  }
}
opportunity.wonDeal marked as won
opportunity.won payload
json
1
2
3
4
5
6
7
8
9
{
  "id": "evt_01HZXN8Y9K0M7R6Q5P4N3T2S1A",
  "type": "opportunity.won",
  "createdAt": "2026-05-27T23:34:12.000Z",
  "data": {
    "opportunityId": "opp_456",
    "value": 25000
  }
}
opportunity.lostDeal marked as lost
opportunity.lost payload
json
1
2
3
4
5
6
7
8
9
{
  "id": "evt_01HZXN8Y9K0M7R6Q5P4N3T2S1A",
  "type": "opportunity.lost",
  "createdAt": "2026-05-27T23:34:12.000Z",
  "data": {
    "opportunityId": "opp_456",
    "reason": "budget"
  }
}

Partners

2 events
partner.registeredNew partner registered
partner.registered payload
json
1
2
3
4
5
6
7
8
9
{
  "id": "evt_01HZXN8Y9K0M7R6Q5P4N3T2S1A",
  "type": "partner.registered",
  "createdAt": "2026-05-27T23:34:12.000Z",
  "data": {
    "partnerId": "ptr_789",
    "company": "Partner Co"
  }
}
partner.approvedPartner approved for program
partner.approved payload
json
1
2
3
4
5
6
7
8
{
  "id": "evt_01HZXN8Y9K0M7R6Q5P4N3T2S1A",
  "type": "partner.approved",
  "createdAt": "2026-05-27T23:34:12.000Z",
  "data": {
    "partnerId": "ptr_789"
  }
}

Commissions

2 events
commission.earnedCommission recorded
commission.earned payload
json
1
2
3
4
5
6
7
8
9
10
{
  "id": "evt_01HZXN8Y9K0M7R6Q5P4N3T2S1A",
  "type": "commission.earned",
  "createdAt": "2026-05-27T23:34:12.000Z",
  "data": {
    "commissionId": "com_101",
    "amount": 500,
    "partnerId": "ptr_789"
  }
}
commission.paidCommission paid out
commission.paid payload
json
1
2
3
4
5
6
7
8
9
{
  "id": "evt_01HZXN8Y9K0M7R6Q5P4N3T2S1A",
  "type": "commission.paid",
  "createdAt": "2026-05-27T23:34:12.000Z",
  "data": {
    "commissionId": "com_101",
    "amount": 500
  }
}

Tasks

2 events
task.createdNew task assigned
task.created payload
json
1
2
3
4
5
6
7
8
9
10
{
  "id": "evt_01HZXN8Y9K0M7R6Q5P4N3T2S1A",
  "type": "task.created",
  "createdAt": "2026-05-27T23:34:12.000Z",
  "data": {
    "taskId": "tsk_202",
    "title": "Follow up with lead",
    "assigneeId": "usr_303"
  }
}
task.completedTask marked complete
task.completed payload
json
1
2
3
4
5
6
7
8
{
  "id": "evt_01HZXN8Y9K0M7R6Q5P4N3T2S1A",
  "type": "task.completed",
  "createdAt": "2026-05-27T23:34:12.000Z",
  "data": {
    "taskId": "tsk_202"
  }
}

Forms

1 events
form.submittedForm submission received
form.submitted payload
json
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "id": "evt_01HZXN8Y9K0M7R6Q5P4N3T2S1A",
  "type": "form.submitted",
  "createdAt": "2026-05-27T23:34:12.000Z",
  "data": {
    "formId": "frm_404",
    "leadId": "ld_123",
    "fields": {
      "name": "Jane",
      "email": "jane@acme.com"
    }
  }
}

Delivery Notes

  • Validate the signature header on every webhook request before parsing payloads.
  • Use idempotency-safe processing keyed by event ID to handle retries safely.
  • Respond quickly with 2xx and defer long-running work to background workers.

Looking for currently published events? docs.leadron.io/events