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.

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

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 unless you generate different tokens. See Refresh Webhook Tokens in Salesforce Spiff.

All endpoints in the Spiff Webhook API require a signature header with a SHA-256 hash-based message authentication code (HMAC) digest, in the format t={timestamp},v1={digest}, where {timestamp} is a UTC epoch timestamp and {digest} is a string representation of the HMAC digest.

Here's a JavaScript example for generating a signature.

Replace these values:

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

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

Replace these values:

  • SUBDOMAIN: The subdomain for your Spiff environment.

    • If you're in the US and using Google Cloud Platform, use app.
    • If you're in the US and using Hyperforce, use us1.
    • If you're in the EU and using Google Cloud Platform, use eu.
    • If you're in the EU and using Hyperforce, use eu1.

  • 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

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

  • HASH: The string representation of the HMAC signature that you generated.

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. Make sure that you pass the signature header for every endpoint.

See Also