Salesforce Webhooks: Your Guide to Real-Time Data Integration and More

In today’s hyper-interconnected digital landscape, seamless communications between systems are becoming increasingly essential to the efficient running of business operations. Custom integrations are a great mechanism for outbound communications to distributed applications from within Salesforce, but what about when those systems need to send data back into Salesforce, in real-time?

Due to one of many possible reasons, it simply may not be feasible for us to modify those external systems to utilize the existing Salesforce APIs for returning data back into Salesforce. In these scenarios, webhooks come to the rescue.

What Is a Webhook?

Webhooks can be seen as a special, hands-off, communication method between systems, flipping the traditional paradigm of integrations on its head. Instead of actively fetching data from an external system, webhooks provide a mechanism for a system to send a request to a URL based on an event (as defined by that system) occurring in that system, for example, a record being created or updated.

In simple terms, webhooks are a mechanism for a system to alert another system to some event having happened, allowing the listening system to respond accordingly. In the case of Salesforce, this involves exposing a URL that can passively listen for, receive and handle the event from the other system.

Setting Up a Webhook

Setting up a webhook from within Salesforce can be a slightly confusing task the first time around as there is no specific area within Setup where we can do this. However, by leveraging Salesforce Sites or Experience Cloud, we can provide a publicly accessible URL to the external system that doesn’t require authentication.

Let’s walk through the basic steps to set up a webhook using a Salesforce Site:

1. In Setup, use the Quick Find to navigate to the “Sites and Domains > Sites” section.
2. Create a new site, providing it with a label that relates to the webhook you wish to set up. Everything else can be left as is.
3. Take note of the “Domain Name” and “Path” of the site in the “Custom Urls” list, as this will be used in invoking the webhook.

4. Create an Apex class to act as the webhook handler. It has the following requirements:
   1. Be Global.
   2. Annotated with @RestResource(urlMapping=’myUrlEndpoint’) which defines the URL path that will call this handler.
   3. Have a method annotated with @HttpPost which is invoked when the URL is called. This method can either take in parameters or utilize RestContext to get the body of the request.
   4. Optionally has a return type which is the data returned to the caller.

5. Back in the site settings, click on the “Public Access Settings” and provide the guest user with permission to call this class.
6. Activate the site.

This will set up a webhook which can be invoked by performing an HTTP POST request to “https://sitedomainurl+path/services/apexrest/apexUrlMapping”.

These steps only cover the bare minimum in setting up a webhook. In practice, there needs to be a lot more consideration around how we’re going to process the data received by the webhook, its structure, handling potential errors, and security, all of which are important aspects of any webhook.

Security

Setting up a Salesforce Site, or utilizing Experience Cloud, provides us with a publicly accessible URL that can be used to access data and invoke automations within the org, and as such it should be treated extremely cautiously as mistakes in not only the permissions setup but also the code being invoked, could inadvertently leak data from an org.

There are several steps and considerations we can take to harden our exposed endpoint and improve the safety of our webhooks:

1. Access Control: Authenticating the webhook can be a tricky thing to do, as usually by design webhooks don’t go through the usual OAuth, or similar, flow to get an authenticated session. This doesn’t necessarily mean we can’t limit access to our endpoint, instead, we can use alternative approaches:
   1. Only allow certain IP addresses to invoke the webhook and return a 401 response for unknown IPs.
   2. Check the webhook for authentication or “secret” headers, indicating it’s coming from a known host.
2. Guest User Profile Permissions: Follow the principle of least privileged access, granting your guest user the specific permissions, and only those permissions, that it requires to perform its job. This greatly reduces the chance of a data leak, as the webhook can’t leak what it can’t access. This can be augmented by utilizing a single site and guest user per webhook you need, ensuring a specific webhook can only ever utilize exactly what it needs.
3. Input Validation and Sanitization: Since webhooks accept data from untrusted sources, we should always validate that the data looks like it should (e.g. if updating an account record, the input only includes fields we are expecting to update) and sanitize the data (e.g. if we need to query a record based on the webhook’s data, we sanitize the values). Validation and sanitization can prevent the most common types of attack.
4. Error Handling: If something unexpected happens within our handler apex, we should always catch it and operate accordingly. In some instances, we may hit a recoverable error and can continue gracefully. Other times we may hit something completely unexpected and code execution cannot continue, in these instances, we should still catch the error and return a generic 500 status, as inadvertently these uncaught errors could leak the inner workings of our code and expose data inadvertently.

Incorporating these into your webhook setup can greatly bolster the security of your exposed endpoints and mitigate many of the potential risks.

However, it’s important to stress that security is an ongoing process and it’s crucial to always be aware of any potential attack vectors and update security practices over time.

Summary

Webhooks provide a unique communication method for disparate systems that can easily facilitate data flowing into Salesforce in real-time. However, it’s crucial to prioritize security when setting up webhooks and sometimes planning really pays dividends in ensuring you follow common security principles, such as the principle of least privileged access, and constantly assess the risk of using them.

When security is properly managed, it’s easy to unleash the power of real-time communication, taking your systems to the next level.