Salesforce Docs Portal

Get Started with Salesforce Spiff Webhook API

A webhook provides authorized endpoints for Salesforce Spiff to sync third-party data in real time from an external source. A webhook includes a mapping that specifies how the third-party data maps to Spiff records.

After you set up a webhook and define a mapping, use the Spiff webhook API endpoints to test the webhook authentication, upsert records, or delete records.

1. Create a Webhook and Mapping

To get started, complete these sections in Set Up a Third-Party Connector in Salesforce Spiff in Salesforce Help.

  1. Create a Webhook in Spiff
  2. Configure the Webhook Mapping
  3. Add Connector Fields

important: Make a note of the webhook secret that's generated when you create the webhook in Spiff. This secret is required for authenticating webhook API requests. If you close the window without copying these values, you can’t recover them. You can only generate new tokens. See Refresh Webhook Tokens in Salesforce Spiff.

2. Add the Company UUID

The company_uuid query parameter is optional. We recommend including it in your Spiff Webhook API requests.

  1. In Spiff, go to Admin » Settings » Company Settings.
  2. Copy the Company UUID at the top of the page.
  3. Add the UUID as a company_uuid query parameter on the webhook API request.

For example, use https://SUBDOMAIN.spiff.com/_webhook/mapping/MAPPING_ID?company_uuid=COMPANY_UUID.

You can add this query parameter to any endpoint in the Spiff Webhook API.

3. Generate the HMAC-SHA256 Signature

All endpoints in the Spiff Webhook API require a signature header, which is a HMAC-SHA256 cryptographic hash of the current time, the request body, and the webhook secret. The signature format is t={timestamp},v1={digest}, where {timestamp} is a UTC epoch timestamp and {digest} is a string representation of the HMAC-SHA256 digest.

Here's a cURL example for generating a signature.

export CONNECTOR_ID="WEBHOOK_CONNECTOR_ID"
export COMPANY_UUID="COMPANY_UUID"
export URL="https://SUBDOMAIN.spiff.com/_webhook/connector/$CONNECTOR_ID/test?company_uuid=$COMPANY_UUID"
export SECRET="WEBHOOK_SECRET"
export BODY='{}'
export TIMESTAMP=$(date +%s)
export MESSAGE="${TIMESTAMP}.${BODY}"
export DIGEST=$(printf '%s' "$MESSAGE" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')
export SIGNATURE="t=${TIMESTAMP},v1=${DIGEST}"
echo "SIGNATURE: $SIGNATURE"

curl "$URL" \
  -X PUT \
  -H "signature: $SIGNATURE" \
 -H "content-type: application/json" \
 -d \$BODY \
 -v

Replace these values:

  • WEBHOOK_CONNECTOR_ID: The ID of the webhook connector in Spiff. Go to Admin » Connectors in Spiff, find the Webhook connector, click the three dots menu, and select More Info.

  • COMPANY_UUID: Your company's UUID in Spiff. Go to Admin » Settings » Company Settings and copy the Company UUID at the top of the page.

  • WEBHOOK_SECRET: The webhook secret that you generated in Spiff.

  • SUBDOMAIN: The subdomain for your Spiff environment.

    • If you're in the US, use us1.
    • If you're in the EU, use eu1.

4. Test the Signature

To verify that you generated the HMAC-SHA256 signature correctly, pass the signature in a header with the testWebhook endpoint.


curl "https://SUBDOMAIN.spiff.com/_webhook/connector/WEBHOOK_CONNECTOR_ID/test?company_uuid=COMPANY_UUID" \
 -X PUT \
 -H "signature: t=TIMESTAMP,v1=DIGEST" \
 -H "content-type: application/json"

Replace these values:

  • SUBDOMAIN: The subdomain for your Spiff environment.

    • If you're in the US, use us1.
    • If you're in the EU, use eu1.

  • WEBHOOK_CONNECTOR_ID: The ID of the webhook connector in Spiff. Go to Admin » Connectors in Spiff, find the Webhook connector, click the three dots menu, and select More Info.

    Webhook connector in Spiff, showing the More Info menu option

    The ID is visible in the Webhook Integration Information window.

    Webhook connector in Spiff, showing the ID of the connector

  • COMPANY_UUID: Your company's UUID in Spiff. Go to Admin » Settings » Company Settings and copy the Company UUID at the top of the page.

  • TIMESTAMP: The string representation of the UTC epoch timestamp when the signature was created.

  • DIGEST: The string representation of the HMAC-SHA256 signature that you generated.

5. Find the Mapping ID Used with Other Endpoints

Other endpoints in the Webhook API require a MAPPING_ID, which is the ID of an object that the webhook maps from the third-party data source in Spiff. This ID is different from the CONNECTOR_ID used with the testWebhook endpoint.

  1. In Spiff, go to Data Sources » Synced Objects and Fields.

  2. Scroll to the Webhook connector.

  3. Select a mapping.

    The ID is visible under the mapping name.

    Webhook mapping in Spiff, showing the Object ID of the mapping

You can now use the other endpoints in the Webhook API. See Spiff Webhook API. Pass the signature header with every request. We recommend including the company_uuid query parameter.

note: Each endpoint in the Webhook API allows a maximum payload size of 5 MB.

See Also