When building LangLion integrations, you might want your applications to receive events as they occur in LangLion, so that your backend systems can execute actions accordingly.
To enable webhook events, you need to register webhook endpoints. After you register them, LangLion can push real-time event data to your application’s webhook endpoint when events happen on the LangLion Platform.
Using webhook events are particularly useful for listening to asynchronous events (eg. new invoice has been created, time of lesson has been changed, message has been sent to user and so on).
{
"event":"invoice.created", // type of event
"object":{ // object related to specific event, eg. invoice
"id":2413,
"userId":1014,
"paymentFormId":10,
"date":"2023-11-03 00:00:00",
"soldAt":"2023-07-19 00:00:00",
"paidAt":"2023-07-19 00:00:00",
"dayLimit":14,
"place":"Warszawa",
"statusOffice":2,
"statusOfficeName":"paid",
"statusPrint":2,
"statusPrintName":"paid",
"daysOutdated":null,
"numberId":3694,
[...]
"description":"Payment",
"creatorUserId":2,
"deliveredAt":"2023-11-03 00:00:00",
"schoolId":4,
"connectedId":2268,
"createdAt":"2023-11-03 09:58:00",
"updatedAt":"2023-11-03 09:58:02",
"currencyExchange":null
}
}
When webhook callback fails (HTTP status code different than '200'), there will be a few attempts to deliver a given event to your webhook endpoint for up to 3 days with an exponential back off.
Every webhook event is signed before sending it to your endpoints by including a signature in each event’s Webhook-Signature header. This allows you to verify that the received event can be trusted. Webhook-Signature header is the JSON object with the timestamp and the signature included.
"{"timestamp":1703792536,"signature":"537c90d454bf56647f3d1a822f784f229088aa83ad88e4dcf0ea5bb9265bb04b"}"
It's a good practice to verify event signatures to confirm that received events are sent from LangLion. Signature verification allows to prevent a replay attack when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate such attacks, every includes a timestamp in the Webook-Signature header. Because this timestamp is part of the signed payload, it’s also verified by the signature, so an attacker can’t change the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, you can have your application reject the payload.
$payload = @file_get_contents('php://input');
$headers = getallheaders();
$headerSignature = $headers['Webhook-Signature'];
// parts consist of timestamp and signature
$parts = json_decode($headerSignature, true);
$receivedTimestamp = $parts['timestamp'];
$receivedSignature = $parts['signature'];
// prepare event data in a format ready for signage
$event = sprintf("%s;%s", $receivedTimestamp, $payload);
$mySignature = hash_hmac('sha256', $event, 'api client secret');
print($mySignature === $receivedSignature ? "valid signature" : "invalid signature");
To receive events related to diffrent objects you need to register webhook related to specific type of objects (eg. invoice) and events (eg. created, updated)
$ curl --location 'test.langlion.com/api/v2/webhook' \
--header 'Authorization: Bearer 5470b9d687f47e95bfbc972a7e6a27...' \
--form 'event="invoice.created"' \
--form 'callbackUrl="http://yourapp.com/callback"'
{
"data": {
"webhook": {
"id": 10,
"event": "invoice.created",
"callbackUrl": "http://yourapp.com/callback",
"createdAt": "2023-12-28 17:10:19",
"updatedAt": "2023-12-28 17:10:19"
}
}
}
Required
Optional
No optional parameters.
$ curl --location --request DELETE 'test.langlion.com/api/v2/webhook?id=10' \
--header 'Authorization: Bearer 5470b9d687f47e95bfbc972a7e6a273a31f2dadbf98872b5e4e7b0d06de2f24dbaa8cef221adeafb3045745eaf4559f31afa25e79495b75d891847b77f77e8eac8ab14...'
{
"data": {
"webhook": {
"id": 10,
"isDeleted": true,
"deletedAt": "2023-12-28 20:52:45"
}
}
}
Required
Optional
No optional parameters.
$ curl --location --request GET 'test.langlion.com/api/v2/webhooks' \
--header 'Authorization: Bearer 5470b9d687f47e95bfbc972a7e6a273a31f2dadbf98872b5e4e7b0d06de2f24dbaa8cef221...'
{
"data": {
"webhooks": [
{
"id": 10,
"event": "invoice.created",
"callbackUrl": "http://langlion.local/cb.php",
"createdAt": "2023-12-28 17:10:19",
"updatedAt": "2023-12-28 20:52:45"
}
]
}
}
No parameters.