Fundamentals

Communications between Showpad and your custom CRM connector are performed via HTTP requests and responses in JSON format.

note

All endpoints must use the HTTPS protocol.

Authorization and Security

To ensure the highest possible security, Showpad constructs an authorization signature for each request. You must verify each request's authenticity through this signature and reject any which do not pass your verification.

Details about the signature and how to verify it are described in the following sections.

Showpad Signature Header

Every request from Showpad to your connector includes the following two headers:

• x-showpad-signature-timestamp - A Unix epoch timestamp (in seconds) that corresponds to the moment that the request is fired.

• x-showpad-signature-v1 - A comma-separated string of Base64 HMAC SHA-256 hashes that are generated from the HTTP request body and timestamp header. Each hash is generated for a secret.

Example headers:

x-showpad-signature-v1: FLauBV44UFC2oeY8AHcvGiUaL1Bx+FU5o+6ZM8KBdo0=,jR7SyZM0zpyYdOGZ1tOsv1av1RTmx3RzQyEKu7nHTUg=
x-showpad-signature-timestamp: 1668017345

Signature Verification

Step	Description
1.	Check the timestamp. Extract the HTTP header x-showpad-signature-timestamp from the request. This is a Unix epoch timestamp in seconds that corresponds to the moment that the request was fired. Verify that the timestamp is no older than 5 minutes. If older, discard the request. Otherwise, continue to step 2. ⓘ This step is very important to prevent replay attacks.
2.	Prepare the signed_payload string by concatenating the following values: the JSON payload body   +      .      +   x-showpad-signature-timestamp (as a string) Example: { "hello": "world" }.1669302166
3.	Generate the HMAC-SHA256 hash. In the Online Platform, open the Admin Settings page and select CRM from the Integrations section. Select your CRM Connector to open its settings page. Copy your randomly-generated Endpoints Signature Secret. Compute the HMAC of your signed_payload with a SHA256 hash function and the Endpoint Signature Secret. Be sure that the output of the hash function is serialized to Base64.
4.	Compare hashes. Extract the x-showpad-signature-v1 from the request and split the string on the commas to get a list of signatures. The request is valid if at least one signature in the list exactly matches with your own generated HMAC SHA256 hash.

Idenfication

In order to identify you and your organization, as well as ensure secure communications, the payload of each request's POST body includes the showpadInfo attribute:

{
  "showpadInfo": {
    "subdomain": "myorg",
    "username": "user@company.com",
    "crmInstanceId": "dsflkj2349fddd9asdf"
  },
  … [other endpoint-specific properties]
}

The showpadInfo attribute includes:

subdomain	username	crmInstanceId
Your Showpad subdomain.	The current user's email (as registered in Showpad). Your connector must map the Showpad username to a CRM username or id. We recommend explicitly specifying that the Showpad user's email address exactly matches the email address in your CRM system.	The identifier of your CRM Connector. This can be used to verify that you are using correct connector (if you have multiple connectors).

Response Codes

Your connector should always respond with a standard HTTP response code:

• 200 for successful requests, or
• 201 when the request successfully created a record (logged activity)

Errors and Timeouts

Even the best-laid plans can go astray. The following sections describe how Showpad handles these situations.

Errors

If Showpad receives a response code other than 200 or 201, an error message is displayed to the user in Showpad's Online Platform.

{
  "errorMessage": "CRM System XYZ responded with a USER_UNAUTHORIZED code"
}

You can specify additional information about the error in your response via the errorMessage property. When possible, Showpad will include this additional information in the error message displayed in the Online Platform to faciliate troubleshooting.

Timeouts

Showpad wants to ensure an optimal experience, so we highly recommend that you return responses with the lowest possible latency. A timeout error message is sent after 15 seconds with no response.