@andrewcturing/salesforce-webhooks
v1.1.14
Published
Provides an interface to create webhooks in Salesforce for different SObject events
Downloads
11
Maintainers
Readme
Salesforce Webhooks
Introduction
The purpose of this package is to provide a convenient interface to the Salesforce API in order to create or delete webhooks in the Salesforce platform. It offers a simple interface to create basic webhooks for "created", "updated" or "deleted" events on any SObject type (although such types must be triggerable, as specified by an SObject's metadata)
Please note that this is a Node.js package and hasn't been tested in a browser-like environment.
Getting Started
Installation
Nothing special here: just a regular NPM/Yarn Node.js package.
NPM
npm install --save salesforce-webhooks
Yarn
yarn add salesforce-webhooks
Usage
This package can be used to either create or delete a webhook from Salesforce. It just serves as an interface and convenience tool to do all the required wiring, customization and interaction with Salesforce under the hood. It does not however keep track of created webhooks, it's purpose is not to manage those webhooks beyond creation or deletion of its low-level components.
Instantiation
The interface is exposed through the SalesforceClient
class. To start, create
a new instance of this class by providing the following information about your
Salesforce organization:
- Salesforce auth token: a valid REST API token with write access to the Salesforce SOAP API (see for example the Salesforce REST API Developer Guide)
- Instance: the instance identifier where the target organization is running. See this page for more information.
- API Version: this is an optional parameter. It is set to
50.0
by default, and this is the target version for which this package was developed.
The above parameter names are authToken
, instance
and apiVersion
,
respectively. So, to create a new instance of SalesforceClient
execute the
following code:
const { SalesforceClient } = require("salesforce-webhooks");
const authToken = "a secret API token"; // This is supposed to be secret!
const instance = "na139"; // This is just an example instance.
const client = new SalesforceClient({
authToken,
instance,
apiVersion: "50.0",
});
console.log(client);
// SalesforceClient {
// authToken: 'a secret token',
// metadataApiUrl: 'https://na139.salesforce.com/services/Soap/m/50.0',
// soapApiUrl: 'https://na139.salesforce.com/services/Soap/s/50.0'
//}
Note that the *ApiUrl
properties contain information about the instance and
the API version.
The client parameters can also be extracted from environment variables if they are not provided to the constructor:
export SALESFORCE_API_VERSION='50.0'
export SALESFORCE_AUTH_TOKEN='a secret API token'
export SALESFORCE_INSTANCE='na139'
The constructor will resort to the environment variables above if no valid arguments were provided to it:
const { SalesforceClient } = require("salesforce-webhooks");
const client = new SalesforceClient();
console.log(client);
// SalesforceClient {
// authToken: 'a secret token',
// metadataApiUrl: 'https://na139.salesforce.com/services/Soap/m/50.0',
// soapApiUrl: 'https://na139.salesforce.com/services/Soap/s/50.0'
//}
Webhook Creation
Every webhook creation interface requires users to provide at least the following arguments:
endpointUrl
: the URL of the endpoint that the webhook should call whenever it gets triggeredsObjectType
: the type of SObject that this webhook will react to
The following interfaces serve the purpose of creating webhooks:
createWebhookNew
: creates a webhook that gets triggers when a new object is createdcreateWebhookUpdated
: creates a webhook that gets triggers when an object is updatedcreateWebhookDeleted
: creates a webhook that gets triggers when an object is deletedcreateWebhook
: it takes an additional argumentevent
whose values can be eithernew
,updated
ordeleted
, and it creates a webhook that gets triggers when an event of typeevent
happens to an object
An optional parameter called secretToken
can be provided in order to verify
the authenticity of the HTTP calls at the target endpoint. Whenever the endpoint
receives an HTTP call, it can verify that the X-Webhook-Token
header matches
the secret token provided through the secretToken
argument.
To create a webhook that will make an HTTP POST call to http://example.com whenever a new account is created, run the following code:
const client = new SalesforceClient(...); // See the Instantiation section above.
const webhookOpts = {
endpointUrl: 'http://example.com',
sObjectType: 'Account',
secretToken: 'some secret arbitrary string',
};
const webhookData = await client.createWebhookNew(webhookOpts);
console.log(webhookData);
// {
// remoteSiteName: 'SW_Endpoint_9c680f2bb526a0fbdc34a2aef7e5',
// classNames: [
// 'SW_SObjectFactory_3452ca73469dc9c2094f01',
// 'SW_Callout_ae23bd24aa8c2abbc0c78db11e7f',
// 'SW_CalloutMock_6a18a2dfa993157c6574bd7c',
// 'SW_Test_85d9edee3617e831a7fbfe43cb30e084'
// ],
// triggerNames: [ 'SW_Trigger_b868fb7dbbcdea44930014e7a585' ]
// }
If you don't know the type of event at compile time, you can use the more
flexible interface createWebhook
which allows you to specify the type of event
at runtime. The output of the following code is equivalent to the one in the
code above:
const client = new SalesforceClient(...); // See the Instantiation section above.
const webhookOpts = {
endpointUrl: 'http://example.com',
sObjectType: 'Account',
secretToken: 'some secret arbitrary string',
event: 'new'
};
const webhookData = await client.createWebhook(webhookOpts);
console.log(webhookData);
// {
// remoteSiteName: 'SW_Endpoint_9c680f2bb526a0fbdc34a2aef7e5',
// classNames: [
// 'SW_SObjectFactory_3452ca73469dc9c2094f01',
// 'SW_Callout_ae23bd24aa8c2abbc0c78db11e7f',
// 'SW_CalloutMock_6a18a2dfa993157c6574bd7c',
// 'SW_Test_85d9edee3617e831a7fbfe43cb30e084'
// ],
// triggerNames: [ 'SW_Trigger_b868fb7dbbcdea44930014e7a585' ]
// }
The information returned by these methods is required whenever you wish to delete the resources created by them.
Webhook Deletion
As mentioned in the previous section, after creating a webhook the call returns useful data that can be used to delete all the resources created before.
So after creating a webhook, we can do this to delete it:
await client.deleteWebhook(webhookData);
Additional Context
The concept of webhooks in Salesforce is a bit blurry: they do not exist explicitly, but the platform provides enough building blocks for developers to implement them.
Apex
This section briefly describes the Lightning Platform aspects that this package leverages to implement webhooks in Salesforce. In a nutshell:
- Salesforce has a runtime environment within the platform (called Lightning Platform) in which developers can compile, test, deploy and execute arbitrary code. This code is written in a special programming language called Apex
- Apex is a strongly-typed object-oriented programming language whose main
building blocks are
classes
and
triggers:
- Classes share the similar semantics as any other object-oriented programming language in the sense that they offer inheritance, encapsulation and polymorphism.
- Triggers are a particular kind of program that reacts (or gets triggered) by a predetermined set of events (e.g. whenever a new account is created, or when some contact information is updated). They can describe arbitrary logic, however it is usually encouraged to keep such logic as simple/thin as possible (think controllers in the MVC model).
- Apex code can be operated under the usual development cycle where code is
developed locally, compile and tested in the environment, and deployed.
Depending on the type of environment in which the developer works, there are
certain requirements that the code must meet in order to make it to production:
- For production organizations, tests are mandatory and they must succeed in order for the code to be deployed. Also, overall test coverage cannot drop below 75%, so if the new code causes the overall test coverage to go below that threshold it won't get deployed.
- For developer or sandbox organizations, code just needs to compile.
- In order for code to make HTTP calls to 3rd party URL's (i.e. the usual webhook case), the organization must be explicitly configured to "whitelist" such URL's. This is called Remote Site Setting.
Approach
Under the hood, this package performs the following actions when creating a webhook:
- Creates a Remote Site Setting for the provided endpoint URL. This will allow the Apex code to make HTTP calls to such endpoint.
- Deploys some supporting Apex classes that do not depend on the input parameters (e.g. mocking class, factory class, the HTTP callout, etc.)
- Based on the event type and SObject type parameters, a customized trigger is deployed that will get called whenever such an event happens to the specified SObject type. This trigger will get executed and will make an HTTP call to the provided endpoint URL. Please note that for a single event on an SObject instance, multiple triggers can be executed, depending on the currently deployed Apex triggers. If you creat multiple webhooks with the same parameters, their endpoint will receive as many HTTP calls as the number of equivalent webhooks.
Upon successful creation of a webhook, the package returns an object with
information relative to all the entities created above. This information must be
stored for future use whenever users which to clean-up those resources. The
package itself does not keep track of those resources after the call to
createWebhook*
completes.
For deletion, the same steps described above is performed in reverse order, except that instead of creating those resources, they are removed.