It's important for Longship to remain scalable and secure. Any integrations with external systems should not endanger these principles. A webhook is one of those system integration options.
Security
To prevent sensitive data being send over an unsecure connection, it's not recommended to send detailed data. A better solution would be to send only the data that will be needed to get the details via the API.
Performance
An external system that does not perform well, could possibly be a problem for the Longship system because it might result in a long running HTTP call. This is not desirable. This is one of the reasons why the timeout for the webhook receiver is only 5 seconds. Another performance issue could arise when sending large amounts of data.
Cloud events
The aforementioned issues are solved by using cloud events. This basically means that a webhook receiver will only get the data that is relevant to the event type. In every cloud event a reference is available to the Longship API to get all details for the subject of the event type.
| Expected response | 200-299 |
| Request timeout | 5 seconds |
| Retry | 3 times with an exponential back-off up to 15 seconds |
A sample of a cloud event:
The subject is the ID that can be used to get all details from the Longship API. De source points to the specific endpoint. In this sample that would combine into the following URL:
https://api.longship.io/v1/sessions/34B20B7B66234F5794F59D97F7D1A386 Architecture for external systems
To make sure that a response to the webhook request is done as quickly as possible, the actual processing of the event should be done asynchronously. An implementation could be to store the event on a Queue storage system.
Once the event is stored in the queue, another service can use the Longship API to get the details and process the data to its business needs.
