Integrations API

External Service Integrations are used to configure external raters, webhooks, and autofill.

Endpoint Index

Action	Endpoint
Fetch external service integrations	GET /integrations
Add an external service integration	POST /integrations
Update an existing external service integration	PUT /integrations/{integrationName}
Remove an existing external service integration	DELETE /integrations/{integrationName}

Details

Note

The following endpoints require admin authentication. See admin authentication for details.

Fetch external service integrations¶

GET /integrations

Response: ExternalServiceIntegrationsResponse

ExternalServiceIntegrationsResponse¶

required
externalServiceIntegrations [ExternalServiceIntegrationResponse]

ExternalServiceIntegrationResponse¶

required
name string
headers map<string,string>
tenantLocator string
type string external_rater | data_autofill | webhook
url string

optional
securitySpec SecuritySpecification

SecuritySpecification¶

optional
hmacEnabled boolean
secret string
secureSSL boolean
tag string

A SecuritySpecification may only be supplied for an ExternalServiceIntegrationAddRequest with an https:// URL. If secureSSL is false, certificate validation will be disabled. A tag can be supplied along with a secret to help identify which secret is currently in use, and cannot be supplied without a secret. The hmacEnabled flag determines whether the socotra-signature header will be supplied as part of the message with the service using that integration.

Add an external service integration¶

POST /integrations

Request:

Name	Position	Type	Required
request	body	ExternalServiceIntegrationAddRequest	required

Response: ExternalServiceIntegrationsResponse

ExternalServiceIntegrationAddRequest¶

required
name string
url string

optional
headers map<string,string>
securitySpec SecuritySpecification
type string external_rater | data_autofill | webhook

Update an existing external service integration¶

PUT /integrations/{integrationName}

Request:

Name	Position	Type	Required
integrationName	path	string	required
request	body	ExternalServiceIntegrationUpdateRequest	required

Response: ExternalServiceIntegrationsResponse

ExternalServiceIntegrationUpdateRequest¶

required
url string

optional
headers map<string,string>
securitySpec SecuritySpecification

Note

Prior releases of ESI security features followed a “merge” model for updates. Updates now follow PUT semantics, expecting each update request to be a full representation of desired settings. Omitted optional properties will take default values.

Remove an existing external service integration¶

DELETE /integrations/{integrationName}

Request:

Name	Position	Type	Required
integrationName	path	string	required

Response: ExternalServiceIntegrationsResponse

Security Features

https:// integration endpoints can be configured with a SecuritySpecification encompassing the following:

A secret to be used in an HMAC signature (see RFC 2104 - Keyed-Hashing for Message Authentication) that will be supplied in the socotra-signature header of messages sent to that endpoint.
A tag to label which secret is currently in use. Must be between 2 and 32 characters, inclusive.
An hmacEnabled flag that determines whether the socotra-signature should be derived and sent in message headers.
A secureSSL flag that toggles TLS certificate verification. It is true by default.

secret can only contain alphanumeric characters and underscores, with a length between 32 and 64 characters.

The tag is optional, intended as a convenience that can facilitate secret rotations by ensuring that message recipients can easily identify which secret was used to generate the signature value. Even if there are in-flight messages using an old shared secret when you update the secret on the Socotra platform (with a new tag), your receiving code can identify those by the prior tag and use the corresponding prior secret value to verify the signature.

Note

The ability to disable TLS certificate verification is provided for testing and configuration purposes. It should not be left as false in production systems handling real customer data.

Signature Verification

The socotra-signature header takes the following form:

socotra-signature: t=<timestamp>,v1=<signature>,tag=<tag>

timestamp is the UTC timestamp associated with the event transmission, in milliseconds.
signature is the SHA-256 HMAC-hashed signature of the concatenated values timestamp.JSONpayload.tag. If there is no tag associated with the shared secret, then the value is derived from timestamp.JSONpayload.
tag is the optional tag name supplied in SecuritySpecification as a label for the current shared secret.

For verification, the signature derivation can be performed with standard cryptographic library functions in all popular programming languages. Below is an example in JavaScript:

const crypto = require('crypto');

const secret = 'abracadabraabracadabraabracadabraabracadabraabracadabra';

const timestamp = '1695835536124';
const jsonPayload = '{"id":"20012343863","transactionId":"254cb37e-43c4-4102-845a-fbfc5978537d","timestamp":1695835536078,"data":{"username":"alice.lee"},"type":"login.success","username":"alice.lee"}'
const tag = 'secret-1';

const algorithm = 'sha256';
const hmac = crypto.createHmac(algorithm, secret);

hmac.write(`${timestamp}.${jsonPayload}.${tag}`);
hmac.end();

const hash = hmac.read().toString('hex');
console.log("HMAC: ", hash);