Webhooks
Our first Blog on the Basecone developer website is about ‘the implementation of Webhooks’. Basecone is currently implementing webhooks as this is the enabler for Third Party applications and systems to integrate with Basecone.
In this first blog, we will share a bit more information on the principals of Webhooks from a Basecone perspective and what this means when you – as a developer – would like to establish an integration with Basecone.
Please feel free to respond or comment on this subject. Basecone will provide more information and will respond as soon as possible to your questions, suggestions and/or remarks.
What are webhooks?
Webhook notifications are messages indicating that an event in Basecone has occurred. Rather than requiring you to pull information via our API, webhooks push information to your application (in real-time) when certain, specific events occur. These events can be used to update your system or trigger business processes.
Why do we like Webhooks and why should you use it?
Webhooks deliver an open-end integration with Basecone. The advantage of using these hooks can be found in the ease of setting up the connection/ integration with Basecone, but also the number of events that can be pushed from Basecone. As a developer there is no need to build a ‘poll- mechanism’ but can connect to the events of Basecone. A common use-case is the integration with an ERP system. Whenever a transaction is finished within Basecone, the ERP system is notified of the event. The ERP system is now able to collect the transaction via our API and process it accordingly.
Dashboard integration is another common use-case. Dashboards can be live updated on the receipt of events.
How does it work?
Third Party Applications or Systems need to register the application or system via our website: developers.basecone.com. After completing your registration you will have the possibility to connect one or multiple companies (NL: administraties) via the Basecone Webportal. If a specific company is connected, the Third Party Application or System immediately receives the events that they are subscribed to.
How does it work technically?
When an event occurs (e.g. a document is uploaded) Basecone creates an event object. This object contains all the relevant information, including the type of event and the data associated with that event. Events are then delivered via HTTPS POST in JSON format to a destination endpoint of your choice (as specified during registration).
Certain events can be enriched by custom values. These custom values add information to an event, needed by the Thrid Party Application or System. When registering your application at developers.basecone.com, you have the option to define and specify custom fields. If you use these custom fields, they need to be filled out in the Basecone Application (webportal) for each Company individually. The value of these fields will be sent automatically together with the event.
How about reliability?
If the webhook destination responds with any HTTP status code other than 200 (Success), we will consider it a failure. The request is also considered a failure if Basecone does not receive a response within 5 seconds. In case webhook destination responds with the status code 401 (Unauthorized), the webhook will be automatically unsubscribed, in all other cases we will resend the webhook notification every hour for a period of a week until the destination responds with an HTTP status code of 200. This way we ensure Basecone has done it’s utmost best to deliver the event to a Third Party Application or System.
How about security?
We designed webhooks with security in mind. Events are sent through secured connections (https). Also, authorization headers containing username and password can be send along with the event, so the endpoint which is listening for events (Consumer) can be shielded from unauthorized use.