Webhooks
In this guide, we will look at how to register and consume webhooks to integrate your app with LSP.expert. With webhooks, your app can know when something happens in LSP.expert, such as someone adding a job or sent an invoice.
Registering webhooks
To register a new webhook, you need to have a URL in your app that LSP.expert can call. You can configure a new webhook in the LSP.expert under API settings. Give your webhook a name, pick the events you want to listen for, and add your URL.
Now, whenever something of interest happens in your app, a webhook is fired off by LSP.expert. In the next section, we'll look at how to consume webhooks.
Consuming webhooks
When your app receives a webhook request from LSP.expert, check the type attribute to see what event caused it. The first part of the event type will tell you the payload type, e.g., a job, invoice, etc.
Example webhook payload
{
"id": "a056V7R7NmNRjl70",
"type": "job.updated",
"createdAt": "2024-11-18T09:50:52.661Z",
"data": {
"id": "WAz8eIbvDR60rouK"
// ...
}
}
In the example above, a job was updated, and the payload type is a job.
Event types
Here are all the event types you can listen for:
job.created
A new job was created.
job.updated
An existing job was updated.
job.deleted
A job was successfully deleted.
job.in-progress
A job is in progress.
job.finished
A job was finished.
job.invoiced
A job was invoiced.
job.cancelled
A job was cancelled.
job.on-hold
A job is on hold.
job.outsourcing.added
A new outsourcing was added to a job.
job.outsourcing.updated
An existing outsourcing was updated.
job.outsourcing.deleted
An outsourcing was successfully deleted.
job.outsourcing.accepted
An outsourcing was accepted.
job.outsourcing.rejected
An outsourcing was rejected.
job.outsourcing.in-progress
An outsourcing is in progress.
job.outsourcing.ready-for-review
An outsourcing is ready for review.
job.outsourcing.finished
An outsourcing was finished.
job.outsourcing.cancelled
An outsourcing was cancelled.
job.outsourcing.on-hold
An outsourcing is on hold.
group.created
A new group was created.
group.updated
An existing group was updated.
group.deleted
A group was successfully deleted.
group.in-progress
A group is in progress.
group.finished
A group was finished.
group.invoiced
A group was invoiced.
group.cancelled
A group was cancelled.
group.on-hold
A group is on hold.
client.created
A new client was created.
client.updated
An existing client was updated.
client.deleted
A client was successfully deleted.
supplier.created
A new supplier was created.
supplier.updated
An existing supplier was updated.
supplier.deleted
A supplier was successfully deleted.
invoice.created
A new invoice was created.
invoice.updated
An existing invoice was updated.
invoice.deleted
An invoice was successfully deleted.
invoice.sent
An invoice was sent.
invoice.paid
An invoice was paid.
invoice.credited
An invoice was credited.
quote.created
A new quote was created.
quote.updated
An existing quote was updated.
quote.deleted
A quote was successfully deleted.
quote.sent
A quote was sent.
quote.accepted
A quote was accepted.
quote.rejected
A quote was rejected.
expense.created
A new expense was created.
expense.updated
An existing expense was updated.
expense.deleted
An expense was successfully deleted.
expense.paid
An expense was paid.
purchaseOrder.created
A new purchase order was created.
purchaseOrder.updated
An existing purchase order was updated.
purchaseOrder.deleted
A purchase order was successfully deleted.
purchaseOrder.sent
A purchase order was sent.
purchaseOrder.finished
A purchase order was finished.
Example payload
{
"id": "krPLDFQP52HEfrFkbqtFJ",
"type": "job.created",
"createdAt": "2024-11-25T08:41:20.886Z",
"data": {
"object": "job",
"id": "67443830957cd3c1903bb7f3",
"accountId": "6718a0b50e27164043ce9130",
"pinned": false,
"name": "Brochure 2024",
"additionalInfo": null,
"dueDate": "2024-11-25T09:00:00.000Z",
"startDate": null,
"status": 1,
"progress": 0,
"archive": false,
"quantity": {
"unitCostPriceReference": {
"type": "account",
"id": "6718a10e0e27164043ce9bbd"
},
"catFile": { "fileIds": [] },
"hasMatches": false,
"value": 2500,
"unitCost": 0.14,
"timeBasedUnitCost": 0,
"matchesType": "fixed",
"matches": []
},
"quantityType": { "id": "6718a0f90e27164043ce96a7", "name": "Words" },
"client": { "id": "6718a1350e27164043ce9e80", "name": "Microsoft" },
"service": { "id": "6718a0f90e27164043ce95c0", "name": "Translation" },
"fixedPrice": { "currency": { "code": "EUR", "symbol": "€" } },
"applyMinimumFee": true,
"timeBasedInvoice": false,
"timeTrackers": { "running": false, "duration": 0, "list": [] },
"user": { "id": "6718a0b50e27164043ce912e", "name": "Cédric Degallaix" },
"nonBillable": false,
"discount": 0,
"extraCharge": { "type": "percentage", "percentage": 0, "amount": 0 },
"createdAt": "2024-11-25T08:41:20.805Z",
"updatedAt": "2024-11-25T08:41:20.862Z",
"labels": [],
"notes": [],
"files": [],
"outsourcing": [],
"estimation": {
"type": "estimation",
"isV2": true,
"total": 350,
"totalInvoiced": null,
"currency": { "code": "EUR", "symbol": "€" },
"partialInvoiced": null,
"details": {
"subtotal": 350,
"total": 350,
"discount": { "value": 0, "amount": 0 },
"extraCharge": { "percentage": 0, "amount": 0, "type": "percentage" },
"matches": [],
"quantity": {
"value": 2500,
"quantityType": { "id": "6718a0f90e27164043ce96a7", "name": "Words" }
},
"unitCost": 0.14,
"service": { "id": "6718a0f90e27164043ce95c0", "name": "Translation" },
"currency": { "code": "EUR", "symbol": "€" },
"minimumFeeApplied": false,
"totalDetails": {
"extraCharge": { "amount": 0, "discount": 0, "total": 0 },
"subtotal": { "amount": 350, "discount": 0, "total": 350 },
"total": 350
}
},
"outsourcing": { "suppliers": [], "totals": [] },
"profitability": {
"withMargin": { "status": "incorrectStatus" },
"status": "incorrectStatus"
},
"performance": { "status": "incorrectStatus" }
}
}
}
Security
To know for sure that a webhook was, in fact, sent by LSP.expert instead of a malicious actor, you can verify the request signature. Each webhook request contains a header named x-lsp-expert-signature, and you can verify this signature by using your secret webhook key. The signature is an HMAC hash of the request payload hashed using your secret key. Here is an example of how to verify the signature in your app:
Verifying a request
const signature = req.headers['x-lsp-expert-signature']
const hash = crypto.createHmac('sha256', secret).update(payload).digest('hex')
if (hash === signature) {
// Request is verified
} else {
// Request could not be verified
}
If your generated signature matches the x-lsp-expert-signature header, you can be sure that the request was truly coming from LSP.expert. It's essential to keep your secret webhook key safe — otherwise, you can no longer be sure that a given webhook was sent by LSP.expert. Don't commit your secret webhook key to GitHub!