Many third-party applications offer their own APIs or webhooks, facilitating seamless and often simplified integrations across platforms. Another integration approach may involve using middleware or an enterprise service bus (ESB) to facilitate data movement. Regardless, the Salesforce REST API can handle standard CRUD operations (create, read, update, and delete), or you can develop custom Apex logic and expose it through the REST API to streamline processing.
Consider the scenario of integrating Stripe with Salesforce. Stripe excels in processing credit cards and managing subscription and payment details, while Salesforce effectively manages interactions between your business and customers. It makes sense to have Stripe notify Salesforce when a payment is made, keeping your team informed.
Before delving deeper, let’s introduce a key concept. A webhook is an HTTP callback triggered when a specific event occurs. An application implementing webhooks will POST a message to a URL upon such events. In this example, Stripe will send a JSON message to Salesforce, where Salesforce will consume the message and perform additional processing based on the JSON content.
If you have experience with web services development, you’re aware that the Salesforce REST API can handle various tasks without requiring custom Apex classes. The API enables querying records, inserting new records, updating records, deleting records, and more. To demonstrate the API’s capabilities and emphasize its power, we’ll create a custom Apex class for performing multiple operations.
Now, let’s delve into the example. For simplicity, let’s assume that the JSON posted to our Salesforce endpoint will be structured as follows:
{
"id": "ch_abcdefghijklmnopqrstuvwx",
"amount": 9900,
"description": "greg@interactiveties.com",
"source": {
"id": "card_19mlu82GgpHzUJkgFLGaSS8e",
"brand": "American Express",
"exp_month": 11,
"exp_year": 2020,
"last4": "2222",
"name": "greg@interactiveties.com",
},
"status": "succeeded",
"type": "charge.succeeded"
}
Our task is to transform this JSON request into an object usable within our Apex class. Subsequently, we will perform a query to locate a Contact with the email address specified in the value for the description, in this instance, “greg@interactiveties.com.” Once we identify the contact, we will utilize certain attributes from the JSON object to generate a corresponding Task record associated with the Contact obtained from our query.
As a response to the request, we will furnish the Task’s Id that we created along with a success message. The JSON we send in response will be formatted as follows:
{
"status": "success",
"contactid": "0033000000YVLQWAA5",
"taskid": "00T3000000rEvJtEAK",
"message": ""
}
Now that the objective is clear, let’s proceed to the Apex class:
/*
Created by: Greg Hacic
Last Update: 17 February 2017 by Greg Hacic
Questions?: greg@ities.co
Notes:
- API endpoint accepts JSON similar to:
{
"id": "ch_abcdefghijklmnopqrstuvwx",
"amount": 9900,
"description": "greg@interactiveties.com",
"source": {
"id": "card_123456789123456789123456",
"brand": "American Express",
"exp_month": 11,
"exp_year": 2021,
"last4": "2222",
"name": "greg@interactiveties.com"
},
"status": "succeeded",
"type": "charge.succeeded"
}
- queries for the Contact with the email address provided in the description key/value pair from the JSON request
- creates a Task
- returns JSON similar to:
{
"status": "success",
"contactid": "0033000000YVLQWAA5",
"taskid": "00T3000000rEvJtEAK",
"message": ""
}
*/
//@RestResource annotation exposes the class as a REST resource
@RestResource(urlMapping='/demo/createTask/*') //endpoint definition > {Salesforce Base URL}/services/apexrest/demo/createTask/
global class createTask {
//primary logic for the class
@HttpPost //HttpPost annotation exposes the method as a REST resource and called when an HTTP POST request is sent
global static responseWrapper taskCreationLogic() {
RestRequest req = RestContext.request; //the RestRequest for the Apex REST method
responseWrapper responseJSON = new responseWrapper(); //responseWrapper object for API response
String typeOfCard = ''; //placeholder for the type of card string
String last4OfCard = ''; //placeholder for the last four digits of the card
String emailAddress = ''; //placeholder for an email address
Map<String, Object> body = new Map<String, Object>(); //placeholder for the JSON Body of the request
Map<String, Object> src = new Map<String, Object>(); //placeholder for the source object from the JSON request
String jsonBody = req.requestBody.toString(); //the body of the request
if (!String.isBlank(jsonBody)) { //if the request body is NOT white space, empty ('') or null
body = (Map<String, Object>)JSON.deserializeUntyped(jsonBody); //deserializes the JSON string into collections of primitive data types
if (body.containsKey('description')) { //if there is a key of description in our body map
emailAddress = (String)body.get('description'); //grab the value for the description key from the body map and cast it to a string
List<Contact> queriedContacts = [SELECT Id FROM Contact WHERE Email = :emailAddress ORDER BY CreatedDate DESC LIMIT 1]; //query for a Contact that has the email address
if (!queriedContacts.isEmpty()) { //if the list is not empty
if (body.containsKey('source')) { //if there is a key of source in our body map
src = (Map<String, Object>)body.get('source'); //grab the value for the source key from the body map and cast it to a new map (String > primative data types)
if (src.containsKey('brand')) { //if there is a key of brand in our src map
typeOfCard = (String)src.get('brand'); //grab the value for the brand key from the src map and cast it to a string
}
if (src.containsKey('last4')) { //if there is a key of last4 in our src map
last4OfCard = (String)src.get('last4'); //grab the value for the last4 key from the src map and cast it to a string
}
}
responseJSON.contactid = queriedContacts[0].Id; //populate the Id of the Contact record to our response object
Task newTask = new Task(ActivityDate = Date.Today(), Description = 'The '+typeOfCard+' credit card ending in '+last4OfCard+' was charged.', Status = 'Complete', Subject = typeOfCard+' Card Charged', WhoId = queriedContacts[0].Id); //create a Task
Database.SaveResult insertNewTask = Database.insert(newTask); //insert the new Task
if (!insertNewTask.isSuccess()) { //if the insert DML was NOT successful
List<Database.Error> errors = insertNewTask.getErrors(); //grab the error array from the SaveResult object
//respond with failure
responseJSON.status = 'failure';
responseJSON.message = errors[0].getMessage(); //set the message to the first error in the array
} else { //otherwise, the insert was successful
responseJSON.taskid = insertNewTask.getId(); //populate the Id of the Task record to our response object
}
} else { //otherwise, no key of source in our map
//respond with failure
responseJSON.status = 'failure';
responseJSON.message = 'There are no Contacts with the email address of '+emailAddress+'.';
}
} else { //otherwise, no key of description in our map
//respond with failure
responseJSON.status = 'failure';
responseJSON.message = 'No description in the JSON request.';
}
} else { //otherwise, the JSON body was white space, empty ('') or null
//respond with failure
responseJSON.status = 'failure';
responseJSON.message = 'Things basically broke...';
}
return responseJSON; //return the JSON response
}
//wrapper class for the response to an API request
global class responseWrapper {
global String status {get;set;} //status string
global String contactid {get;set;} //18 character Contact record Id
global String taskid {get;set;} //18 character Task record Id
global String message {get;set;} //message string
//constructor
global responseWrapper() {
//default all values
this.status = 'success';
this.contactid = '';
this.taskid = '';
this.message = '';
}
}
}
The aim of this post is to offer you an example that can be utilized alongside existing samples in the developer community. This is intended to enhance your understanding of the fundamental concepts and options available for developing REST API Web Services with Salesforce.