Webhooks are an awesome way to receive data as it happens on the platform. You can setup automations, scripts or alerts based on incoming data from webhooks and bring your application to life without having to ever probe or mess with the REST API.
¶ Create a webhook
FsHub allows you to create a webhook:
¶ For your Account
Go to your Account Settings and head over to the Integrations page.
Inside this area you can create or view your webhooks.
You can create a webhook by clicking the Add a webhook button.
You will need to enter the following details for your webhook:
- Endpoint: The URL that the webhook will send a POST request to
- Enabled?: Allows you to 'pause' sending webhooks without deleting the webhook
- Events: Select which events you wish your webhook to be triggered for
¶ For your Virtual Airline
Go to the Integrations area of the VA Crew Portal
Inside this area you can create or view your webhooks. You can create a webhook by clicking the Add a webhook button.
And now fill the details!
- Name: Name your Webhook, this is useful when using multiple hooks for different purposes.
- Endpoint: The URL that the webhook will send a POST request to
- Discord Server? Select this, if you are not developing an own application. This checkbox makes sure, that your Webhook is formatted for Discord
If you want more sofisticated alerts and messages, we can recommend the third party service FsHub2Discord.
- Enabled?: Allows you to 'pause' sending webhooks without deleting the webhook
- Events: Select which events you wish your webhook to be triggered for
¶ Receiving Webhooks
FsHub can dispatch webhooks via either HTTP or HTTPS to a server of your choice. Your server does not have to specifically be a webserver or explicitly listen to port 80 or 443, or even a FQDN. You can provide an IP and a port (xxx.xxx.xxx.xxx:yyyy) as well.
The path to your webhook can also be anything you desire, e.g. https://example.com/i/love/webhooks as long as its a valid URL.
When receiving a webhook, you must acknowledge it to FsHub by responding with an HTTP status code response of 200.
If you do not, FsHub will keep retrying to dispatch it again for 10 times over a period of 40 minutes, and afterwards the webhook will be disabled.
You will receive an e-mail from FsHub informing you when a webhook gets disabled. You can just renable your webhooks in these cases if you got everything working again.
If FsHub detects abuse of this feature, we may disable your account from creating webhooks. Please only re-enable webhooks you are sure are functional.
¶ Webhook Events
We are reworking this section, please visit the FsHub for Developers Archive for a list of the events & examples.
¶ Optimal Settings
These are some settings & functions we strongly recommend you apply to your application to ensure your webhooks are received with no issues.
¶ Ensure you can receive large payloads on POST requests
By default a lot of webservers will not support payloads larger than a few MBs (e.g. in PHP the limit is 2MB), however some webhooks can include a lot of data from a flight, thus producing a payload over this default limit.
The recommended limit is at least 32MBs. This may change in the future as we may include more data in payloads, so it's best to keep an eye on this page if you ever have failure receiving events in the future due to payload issues.
Not all endpoints will include that much data, if you are limited due to your hosting solution to the default values, you can use alternative events based on the documentation.
¶ Example for NGINX
Edit your nginx configuration to include this value in your server clause:
server { … client_max_body_size 32M; }
If you are using NGINX Proxy Manager, you can include the above value under the Advanced > Custom Nginx Configuration.
¶ Example for Apache HTTPD
Include this value in your configuration file:
LimitRequestBody 33554432
¶ Example for PHP
Set these to your php ini configuration file:
memory_limit = 32Mpost_max_size = 32Mupload_max_filesize = 32M
¶ Cross-Site Request Forgery (CSRF)
If you are using a modern web application framework such as Laravel, dotNET, Django, Ruby On Rails and others, these frameworks, by default may implement CSRF protection and as such, will prevent HTTP POST requests from being accepted by your server without "route exceptions" being added.
This is a topic that you should investigate if you realise that you are unable to successfully process the incoming FsHub webhooks.