How to manage Webhooks on Leanbe
Introduction
In Leanbe, Webhooks are an effective way to integrate your Leanbe account with external services and tools in real-time. This article aims to guide you through the setup and utilization of Webhooks in Leanbe.
What are Webhooks? 🤔
Webhooks are automated messages sent from one app to another when something happens. They have a message, a trigger, and an action. In Leanbe, you can use webhooks to get notified about events that occur within your product, like when an idea is created, updated, or deleted.
How to Set Up Webhooks in Leanbe 🛠
Step 1: Accessing Webhooks Settings 🖥
Log in to your Leanbe account.
Navigate to the product for which you want to set up Webhooks.
Go to Product Settings -> Webhooks.
Step 2: Configuring a Webhook 🔧
Inside the Webhooks settings, enter the Webhook URL where you want Leanbe to send the Webhook payloads.
Once you enter the URL, a Webhook Secret will be automatically generated. This secret is essential for verifying the authenticity of the Webhook payloads you receive.
📜 List of Available Events
Leanbe provides a rich set of events that can trigger Webhooks. Here's the full list of events you can use:
Idea Request Events 📩
- ideaRequest.created: Triggered when a new idea request is created.
- ideaRequest.attachedToIdea: Triggered when an idea request is attached to an idea.
- ideaRequest.ignored: Triggered when an idea request is ignored.
Idea Events 📝
- idea.created: Triggered when a new idea is created.
- idea.updated: Triggered when an existing idea is updated.
- idea.promoted: Triggered when an idea is promoted.
- idea.deleted: Triggered when an idea is deleted.
- idea.upVoted: Triggered when an upvote is added to an idea.
- idea.downVoted: Triggered when a downvote is added to an idea.
Customer Events 👥
- customer.created: Triggered when a new customer is created.
- customer.updated: Triggered when customer information is updated.
- customer.deleted: Triggered when a customer is deleted.
Backlog Item Events 📋
- backlogItem.created: Triggered when a new backlog item is created.
- backlogItem.updated: Triggered when a backlog item is updated.
- backlogItem.deleted: Triggered when a backlog item is deleted.
- backlogItem.statusChanged: Triggered when the status of a backlog item changes.
OKR Events 🎯
- okr.created: Triggered when a new OKR is created.
- okr.updated: Triggered when an OKR is updated.
- okr.deleted: Triggered when an OKR is deleted.
Announcement Events 📣
- announcement.created: Triggered when a new announcement is created.
- announcement.updated: Triggered when an announcement is updated.
- announcement.deleted: Triggered when an announcement is deleted.
Webhook Request Structure 📄
The Leanbe webhook request is sent as a JSON object and will contain the following data:
- payload: All the data associated with the event.
- event: The event name which triggered this request.
- triggeredAt: The date and time of this request (PDT Timezone).
- signature: This is the SHA256 hashed data of the payload and your webhook secret.
You can use the signature to ensure that the request is securely coming from Leanbe.
🛡 Verifying Webhook Signature
Every Webhook response from Leanbe contains a signature in the request body. This signature can be used to verify that the request is genuinely coming from Leanbe. The signature is generated using the Webhook Secret via the following formula:
crypto.createHmac('sha256', webhookSecret).update(JSON.stringify(payload)).digest('hex');Here, crypto is a module you might use in Node.js, webhookSecret is the Webhook Secret from your Webhook settings, and payload is the body of the Webhook response. Compare the signature in the response header with the one you generate to ensure the request is authentic.
Example Requests
customer.created
{
"payload": {
"_id": "649d2b399c3a1954e6a2e4b7",
"firstName": "John",
"lastName": "Clarke",
"publicId": "f6256c00-a057-4afa-a59c-021dcbf3e03e",
"email": "johnclarke@example.com",
"phone": "+123456789",
"state": "California",
"city": "San Francisco",
"addressLine1": "123 Main St",
"addressLine2": "Apt 4B",
"zipcode": "12345",
"country": {
"countryCode": "US",
"countryName": "United States"
},
"company": {
"name": "Leanbe",
"jobTitle": "Software Engineer",
"seniority": "Senior",
"salary": "$150,000"
},
"image": {},
"gender": "Male",
"source": "Manual",
"type": "Initiator (innovator, business driver, change agent)",
"confirmed": false,
"products": [
{
"_id": "649bf71bbeac6ade0bed7245",
"name": "Webhook"
}
],
"bgColor": "#4D80CC",
"isTemporary": false,
"devices": [
{
"_id": "device1",
"name": "Device 1",
"deviceType": "Mobile",
"brand": "Samsung",
"system": "Android",
"browser": "Chrome",
"language": "English"
},
{
"_id": "device2",
"name": "Device 2",
"deviceType": "Laptop",
"brand": "Dell",
"system": "Windows",
"browser": "Firefox",
"language": "English"
}
],
"billing_details": [
{
"_id": "billing1",
"plan_type": "Basic",
"plan_tier": "Standard",
"plan_frequency": "Monthly",
"subscription_start_date": "2023-06-01",
"subscription_end_date": "2023-06-30",
"plan_price": "$19.99"
},
{
"_id": "billing2",
"plan_type": "Premium",
"plan_tier": "Pro",
"plan_frequency": "Annual",
"subscription_start_date": "2023-01-01",
"subscription_end_date": "2023-12-31",
"plan_price": "$199.99"
}
],
"notes": [
{
"note": "This is note 1"
},
{
"note": "This is note 2"
}
],
"createdAt": "2023-06-29T06:56:57.314Z",
"updatedAt": "2023-06-29T06:56:57.314Z"
},
"event": "customer.created",
"triggeredAt": "2023-06-29T06:56:57.472Z",
"signature": "b3d9651057e6a4562ede7900eabaadb24e18e85a31cd41c5c150a2b54a848ee6"
}idea.created
{
"payload": {
"_id": "649d2ac49c3a1954e6a2e421",
"owner": {
"_id": "63caa6a0575db9607cd0d171",
"firstName": "John",
"email": "john.doe@example.com"
},
"assigned": {
"_id": "63caa6a0575db9607cd0d171",
"firstName": "Alice",
"email": "alice.smith@example.com"
},
"title": "Dummy Title",
"description": "Dummy Description",
"descriptionHTML": "<p>This is a dummy description</p>",
"tags": [
{
"title": "dummy"
}
],
"visibility": "public",
"promoted": false,
"archived": false,
"upvotes": 0,
"createdAt": "2023-06-29T06:55:00.385Z",
"updatedAt": "2023-06-29T06:55:00.385Z",
"product": {
"_id": "649bf71bbeac6ade0bed7245",
"name": "Dummy Product"
},
"ideaRequests": [
{
"id": "1",
"title": "Add more features"
},
{
"id": "2",
"title": "Improve performance"
}
]
},
"event": "idea.created",
"triggeredAt": "2023-06-29T06:55:00.566Z",
"signature": "5de53cf88464dfb34ab57045ea120e411e0fc76f3dee413f90a5719111545133"
}Conclusion 🎉
Webhooks are a powerful feature in Leanbe, especially when you want to create an integrated and automated workflow between Leanbe and other tools/services. Understanding and setting them up properly can improve your productivity and ensure you stay updated in real-time.
If you have any questions or need further assistance, feel free to reach out to our support team. 💌
Updated on: 29/06/2023
Thank you!