---
schema_version: "1"
id: c1c72abfc33a40b75077b9142a44d6a4b781517ec7ca74f1b0fcc998395a7e2e
title: Get Started with Salesforce Spiff Webhook API
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/sales-cloud/spiff/guides/webhook-api-get-started.md
canonical_url: https://developer.salesforce.com/docs/sales/spiff/guide/webhook-api-get-started.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: cc23b15591d53ae4e7d426d0aaf66614d7eceec41e29dcbb46f410694f2d66eb
products:
  - Salesforce Spiff
  - Sales Cloud
---
# 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](https://help.salesforce.com/s/articleView?id=sales.spiff_connector_third_party_setup.htm&type=5) 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](https://help.salesforce.com/s/articleView?id=sales.spiff_refresh_webhook_token.htm&type=5).

## 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](/docs/sales/spiff/references/spiff-webhook-api-reference?meta=Summary).

## 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.

```curl
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](/docs/sales/spiff/references/spiff-webhook-api-reference?meta=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](https://developer.salesforce.com/docs/media/spiff/webhook-connector-info.png '{"class": "image-full"}')

  The ID is visible in the Webhook Integration Information window.

  ![Webhook connector in Spiff, showing the ID of the connector](https://developer.salesforce.com/docs/media/spiff/webhook-connector-id.png '{"class": "image-full"}')

- `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](https://developer.salesforce.com/docs/media/spiff/webhook-object-mapping-id.png '{"class": "image-full"}')

You can now use the other endpoints in the Webhook API. See [Spiff Webhook API](/docs/sales/spiff/references/spiff-webhook-api-reference?meta=Summary). 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**

- _Salesforce Help_: [Set Up a Third-Party Connector in Salesforce Spiff](https://help.salesforce.com/s/articleView?id=sales.spiff_connector_third_party_setup.htm&type=5)
- _Trailhead_: [Deliver Smarter Incentives with Salesforce Spiff](https://trailhead.salesforce.com/content/learn/trails/deliver-smarter-incentives-with-salesforce-spiff)