Relic Solution: All About Webhooks!

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.

Please read this next: Relic Solution: Troubleshooting Alerts Webhook Notification Channel Issues


Hi @gjohnson

thank you for the article, any examples of webhooking with Jira?

I am trying to do a quick implementation like file a ticket for automated alerts and was wondering if there was an example of webhooks with jira.


Hi @MKhanna thanks for your question. I do not have any examples of a webhook which has been set up for a Jira integration but this has probably been done before by other users. I recommend looking for Jira documentation on how to set up the endpoint and what it expects, then, try setting up the webhook in New Relic. If you find trouble please feel free to reach out to support or to the community again for help.


Is there a way I can send “$AssertionError” in the webhook?

I am using scripted browser under Newrelic Synthetics and need this error to be sent to Webhooks.

Hi @abhineet.raj thanks for your question. I can see that you have opened a support ticket as well so we will work with you in the ticket for now and then post our findings here for the community to see once we’re done.

1 Like

To update the community about the question from @abhineet.raj:

There are ways to customize your webhooks, as you can see in our documentation here:

I believe the closest thing we can currently achieve is to suggest including the details , but beyond that, I don’t believe the error message can be specifically attached to the webhook you have configured. I’ve filed a feature request for this with our Alerting team.


Could new relic webhooks be used to notify a Service Registry that an application is healthy or unhealhty?

Hi, @nbasinger: Webhooks can only notify an endpoint when an alert incident is opened, closed, or acknowledged. If your service registry is intelligent enough to mark an application unhealthy when an incident is opened, and healthy when the incident is closed, then that might work.

Likely you will have to create your own endpoint to receive webhook notifications from New Relic Alerts and determine application health status, then post that information to the registry.


Is there a way to include data columns/categories within the URL parameters, such as web-hook.url/method/{category} ? Or does all the data need to be posted within the payload?

@Baz.Mannion this is not possible at the moment so your best bet would be to add this as a Feature Idea where other users can vote and add their use-cases :slight_smile:

1 Like