What Are Webhooks?
A webhook is a way to send data from New Relic to an outside platform without requiring an SDK or custom integration. In the case of New Relic, our Alerts product makes good use of webhooks.
Webhooks are widely used throughout the software industry because of their simplicity. In order for this simplicity to exist, webhooks do not require a custom UI and they convey information using common standards such as JSON. The advantage of webhooks being composed of so few parts is that they can be used anywhere and take up few resources. The downside of this simplicity is that they are not terribly user-friendly and require an attention to code syntax and other details. They are very similar to REST API calls except that REST API calls are manually performed, whereas webhooks are automatically sent by New Relic and automatically consumed by the receiver.
“When it comes to designing webhooks there is nothing really close to a standard in the HTTP API literacy. Every service implements webhooks differently leading to many different flavors of webhooks implementations out there.”
This means that this guide really only applies to New Relic. Please align your knowledge of webhooks to the specifics laid out here when trying to use New Relic webhooks.
Webhooks are composed of at least 2 parts:
The endpoint (or base URL): The endpoint is the web address for the platform which is receiving the payload sent by New Relic.
The payload: The payload is the information being handed off from one platform to another. This is the place where New Relic puts pieces of information that you want to do something with elsewhere. This can look like JSON or an HTTP POST request.
The endpoint must be set by the user (you) so that the payload has somewhere to go. The payload can either be whatever New Relic happens to send or it can be customized to only send specific New Relic information and whatever useful extras you deem necessary.
In addition to these 2 fields there are also the optional fields of Basic Authentication and Custom Headers. Basic Auth adds a layer of security to the webhook and Custom Headers can provide additional information to the endpoint to help it know what to do with the payload that it receives.
As always, please read the public documentation for all the necessary vital specifics. Consuming this information and disseminating it will save you and your colleagues precious time and allow you to gain the most immediate value from the feature:
What If I Get Stuck Trying To Set One Up?
If you are trying to set up a webhook, but encounter an error, it can be difficult to know exactly what went wrong. This is one of the costs in the simplicity of webhooks. Here are some basic considerations to help you deduce what went wrong:
Each piece of the webhook is a seperate point of failure. Because of this it’s important to test them separately before testing them all together:
Test the endpoint: Know what kind of rules you need to follow when you set the URL for the endpoint. For example, if there is an equals sign (
=) somewhere in the URL , it might need to be changed to its Hex equivalent (
%3d) in order for the payload to be delivered.
Test the payload. Most issues with webhooks fall under this category. The payload must be completely free of syntax errors. Payloads are usually written in JSON. If yours is, always use a JSON linter to make sure your payload has valid syntax before attempting to test it in New Relic. The biggest thing to watch out for is the contents of the payload itself. New Relic might be sending information which cannot be used by the endpoint. The endpoint might require things which are not being sent by New Relic. The payload is a point of compromise which you must check and potentially customize in order to make sure both sides understand one another and play nice.
Verify the other optional fields individually as well. Once all your pieces are verified then put them together in the New Relic webhook fields and send a test notification.
Eventually there’s the chance that even with due diligence you still cannot get it to work. In this case Support and the Explorers Hub are always here to help.