A webhook is a notification sent from Yabber to a defined location on the basis of another action taking place. For example, you might have a new lead arrive in Yabber, or a user might complete a fact find, and you will want that information sent to another system. The webhooks module is an extremely comprehensive suite of tools that permits you to set up these notifications. Yabber includes two webhook systems: a general module (that we're introducing now), and an Advanced system which relies on integration with the Yabber API. The former system is easier to use and integrate with Yabber.
Because we send the notification with a range of fields that we have defined, the destination system should have the capacity to map those fields to others that you have defined. In each request we will include a single value that identifies the record, and you may further query this record via the Yabber API if required.
The Webbooks module is found in the 'Home' menu. The 'Webhooks' menu is to the right of the submenu.
Pictured: The Webbooks module is found in the 'Home' menu. The 'Webhooks' menu is to the right of the submenu.
Note that Webhooks is an advanced module.
Managing Webhooks
The 'Webhooks' panel will initially ask for a Webhook name, description, and endpoint. The first two values are for your reference, but the endpoint is the location where your data will be submitted. Once these values are defined, select the submit button and a panel is returned where you may define optional header and body values. Unitless you know what you're doing, these values can generally be ignored.
Pictured: The returned panel will initially ask for a Webhook name, description, and endpoint. The first two values are for your reference, but the endpoint is the location where your data will be submitted. Once these values are defined, select the submit button and a panel is returned where you may define optional header and body values. Unitless you know what you're doing, these values can generally be ignored.
You may add as many header and body values as required but they will be overwritten by Yabber values if there's a conflict. The relevance of these fields is for those occasions where additional custom data might be required, such as when you use a single endpoint for all notifications but need an 'action_type' of some sort to identify the type of data (don't use 'action' - it's a reserved word). If you have an advanced system set up on our end where webhook filtering is created on the type of lead into a system, for example, the webhook will carry data indicating as such.
When you use various modules an option will now be returned for available webhooks. When the 'action' takes place - such as an email subscription - the webhook will be scheduled. We expect a 20X code to be returned, and any other code repeatedly returned will result in the disabling of the webhook.
Review and Edit Webhooks
You may review and edit webhooks via the 'Review' and 'Sent' panels. The image shows the 'Review' panel with the 'Sent' table shown as an inset. Statistics are measured on our end but not yet returned.
Pictured: You may review and edit webhooks via the 'Review' and 'Sent' panels. The image shows the 'Review' panel with the 'Sent' table shown as an inset. Statistics are measured on our end but not yet returned. Enable and disable webhooks via the green toggle switch.
Example PHP Code
If you're fiddly with PHP and want to play with the data submitted via a webhook, consider the very basic code below. Note that the webhook sent from Yabber will include your personal API Key in the header - you should validate any incoming request before processing. Additionally, a salt, or secret key, may also be added to the header as described above to further validate your requests. It may also be worth building in something to validate the IP address of the server responsible for your requests.
First, at the top of your PHP page, you'll want to include a http_response_code(200) message. Yabber requires a successful 200 or 201 header response. To get all the headers sent in your request, use <getallheaders(), and to get the payload data, use file_get_contents('php://input') (you'll want to use json_decode($data, true) to decode the data, and then, perhaps, file_put_contents() in order to review the request arrays in plain text. While not production worthy in any way whatsoever, the following block of code is a basic way to write the webhook data to a file.
with the entire webhook payload in plain text. In reality, you probably won't build your own applications, but rather send the webhook to an existing application to be handled on their end.
Endpoint: You will copy the above code into a file called something like 'endpoint.php', and then upload it to a discreet directory on a domain (you'll want to delete it after playing with it - there's no validation so it'll become a publicly accessible URL). The location of this file becomes your 'endpoint'.
Returned Data: After a webhook is sent, the receiving application may send data back to Yabber, and this data is recorded and evaluated. Reserved for advanced users, the data sent back may be mapped on our end to action additional tasks.
Integrations: There are times where a client might have a custom CRM or proprietary internal application that prevents us from building in 'global' default features, and it's in these cases where we might build a simple webhook tool to keep their custom CRM systems up-to-date in real time.
Encryption: Data transported over the web is never entirely secure - regardless of any precautions. Not unlike our standard forms (with a body that is encrypted by default to meet finance standards), we provide an option to send encrypted data, with the package decrypted by way of your API key (your API key isn't exposed in the header or body, but you will still need to provide a header value to verify requests). This is an advanced feature that isn't supported by third-party application, so it may only be used when building your own tools.
