--- schema_version: "1" id: 3d17c1658c0401828842e97ef96106f0fa40ea0aed6b017e0cc9f134c442a5ee title: Spiff Webhook API collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/sales-cloud/spiff/references/generated-api-specs/spiff-webhook-api-reference.md canonical_url: https://developer.salesforce.com/docs/sales/spiff/references/spiff-webhook-api-reference source_site: developer.salesforce.com content_type: documentation content_hash: 7019440eadbb889b821ab496526b6965f49f48ade8ebc465284eb36a2bd63c0b products: - Salesforce Spiff - Sales Cloud --- Spiff Webhook API # Spiff Webhook API Upsert or delete records that you sync to Salesforce Spiff from a third-party data source with a webhook. A webhook provides an endpoint that Spiff uses to verify that the data source is legitimate. 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 that you generate in Spiff. 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. For information about creating a webhook and generating the signature header, see [Get Started with Salesforce Spiff Webhook API](/docs/sales/spiff/guide/webhook-api-get-started.html). The `company_uuid` query parameter is optional. We recommend including it with every request. To find this value, go to **Admin » Settings » Company Settings** in Spiff and copy the **Company UUID** at the top of the page. Each endpoint in the Webhook API allows a maximum payload size of 5 MB. **Version:** 1.0.0 ## Servers * `https://{subdomain}.spiff.com/_webhook` Default security: signature. ## Security * `signature` (apiKey) HMAC-SHA256 cryptographic hash of the current time, the request body, and the webhook secret that you generate in Spiff. 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. See [Get Started with Salesforce Spiff Webhook API](/docs/sales/spiff/guide/webhook-api-get-started.html). * API key in header: signature ## Operations ### PUT webhookPutSingleRecord `PUT /mapping/{mapping_id}` Operation ID: `webhookPutSingleRecord`. Upserts an individual record from a third-party data source. #### Parameters * `subdomain` (path, string, required) The subdomain for your Spiff environment. * If you're in the US, use `us1`. * If you're in the EU, use `eu1`. _Example_ ``` us1 ``` * `mapping_id` (path, string, required) ID of an object that the webhook maps from the third-party data source in Spiff. To find this ID, go to **Data Sources » Synced Objects and Fields** in Spiff, scroll to the Webhook connector, and select a mapping. The ID is visible under the mapping name. * `company_uuid` (query, string (guid)) Unique identifier for your company in Spiff. This query parameter is optional. We recommend including it with every request. To find this value, go to **Admin » Settings » Company Settings** in Spiff and copy the **Company UUID** at the top of the page. _Example_ ``` e3804275-aba4-4581-ac23-5b195b1a5f52 ``` * `signature` (header, string, required) HMAC-SHA256 cryptographic hash of the current time, the request body, and the webhook secret that you generate in Spiff. 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. See [Get Started with Salesforce Spiff Webhook API](/docs/sales/spiff/guide/webhook-api-get-started.html). Example: `t=1750092638,v1=d79efcece486e8de2f0384b9b07f2af6cd5859685489f6c1fd71be`. #### Request body Media type: `application/json`. Schema: `object`. _Example: user\_example_ user ``` { "external_id": "12345", "name": "Jane Doe", "email": "jane.doe@company.com" } ``` #### Responses * **200** The request was successful. Media type: `application/json`. Schema: `object`. * `ok` (_boolean_) Example: `true`. * **400** The request was unsuccessful for one of these reasons: * Your endpoint URL is invalid. * The webhook doesn't have any mappings created. See [Get Started with Salesforce Spiff Webhook API](/docs/sales/spiff/guide/webhook-api-get-started.html). * **401** The request was unsuccessful because the HMAC-SHA256 signature is invalid. * **422** The request was unsuccessful because the record's primary key (external\_id) isn't unique or the record contains incorrectly formatted data. ### DELETE webhookDeleteSingleRecord `DELETE /mapping/{mapping_id}` Operation ID: `webhookDeleteSingleRecord`. Deletes an individual record that was previously synced from a third-party data source. #### Parameters * `subdomain` (path, string, required) The subdomain for your Spiff environment. * If you're in the US, use `us1`. * If you're in the EU, use `eu1`. _Example_ ``` us1 ``` * `mapping_id` (path, string, required) ID of an object that the webhook maps from the third-party data source in Spiff. To find this ID, go to **Data Sources » Synced Objects and Fields** in Spiff, scroll to the Webhook connector, and select a mapping. The ID is visible under the mapping name. * `company_uuid` (query, string (guid)) Unique identifier for your company in Spiff. This query parameter is optional. We recommend including it with every request. To find this value, go to **Admin » Settings » Company Settings** in Spiff and copy the **Company UUID** at the top of the page. _Example_ ``` e3804275-aba4-4581-ac23-5b195b1a5f52 ``` * `signature` (header, string, required) HMAC-SHA256 cryptographic hash of the current time, the request body, and the webhook secret that you generate in Spiff. 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. See [Get Started with Salesforce Spiff Webhook API](/docs/sales/spiff/guide/webhook-api-get-started.html). Example: `t=1750092638,v1=d79efcece486e8de2f0384b9b07f2af6cd5859685489f6c1fd71be`. #### Request body Media type: `application/json`. Schema: `object`. _Example: user\_delete\_example_ user ``` { "external_id": "12345" } ``` #### Responses * **200** The request was successful. Media type: `application/json`. Schema: `object`. * `ok` (_boolean_) Example: `true`. * **400** The request was unsuccessful for one of these reasons: * Your endpoint URL is invalid. * The webhook doesn't have any mappings created. See [Get Started with Salesforce Spiff Webhook API](/docs/sales/spiff/guide/webhook-api-get-started.html). * **401** The request was unsuccessful because the HMAC-SHA256 signature is invalid. ### PUT webhookPutMultipleRecords `PUT /mapping/{mapping_id}/bulk` Operation ID: `webhookPutMultipleRecords`. Upserts multiple records from a third-party data source. #### Parameters * `subdomain` (path, string, required) The subdomain for your Spiff environment. * If you're in the US, use `us1`. * If you're in the EU, use `eu1`. _Example_ ``` us1 ``` * `mapping_id` (path, string, required) ID of an object that the webhook maps from the third-party data source in Spiff. To find this ID, go to **Data Sources » Synced Objects and Fields** in Spiff, scroll to the Webhook connector, and select a mapping. The ID is visible under the mapping name. * `company_uuid` (query, string (guid)) Unique identifier for your company in Spiff. This query parameter is optional. We recommend including it with every request. To find this value, go to **Admin » Settings » Company Settings** in Spiff and copy the **Company UUID** at the top of the page. _Example_ ``` e3804275-aba4-4581-ac23-5b195b1a5f52 ``` * `signature` (header, string, required) HMAC-SHA256 cryptographic hash of the current time, the request body, and the webhook secret that you generate in Spiff. 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. See [Get Started with Salesforce Spiff Webhook API](/docs/sales/spiff/guide/webhook-api-get-started.html). Example: `t=1750092638,v1=d79efcece486e8de2f0384b9b07f2af6cd5859685489f6c1fd71be`. #### Request body Media type: `application/json`. Schema: `array of string`. Array of `string`. _Example: multiple\_users\_example_ users ``` [ { "external_id": "12345", "name": "Jane Doe", "email": "jane.doe@company.com" }, { "external_id": "67890", "name": "John Smith", "email": "john.smith@company.com" } ] ``` #### Responses * **200** The request was successful. Media type: `application/json`. Schema: `object`. * `ok` (_boolean_) Example: `true`. * **400** The request was unsuccessful for one of these reasons: * Your endpoint URL is invalid. * The webhook doesn't have any mappings created. See [Get Started with Salesforce Spiff Webhook API](/docs/sales/spiff/guide/webhook-api-get-started.html). * **401** The request was unsuccessful because the HMAC-SHA256 signature is invalid. * **422** The request was unsuccessful because the record's primary key (external\_id) isn't unique or the record contains incorrectly formatted data. ### DELETE webhookDeleteMultipleRecords `DELETE /mapping/{mapping_id}/bulk` Operation ID: `webhookDeleteMultipleRecords`. Deletes multiple records that were previously synced from a third-party data source. #### Parameters * `subdomain` (path, string, required) The subdomain for your Spiff environment. * If you're in the US, use `us1`. * If you're in the EU, use `eu1`. _Example_ ``` us1 ``` * `mapping_id` (path, string, required) ID of an object that the webhook maps from the third-party data source in Spiff. To find this ID, go to **Data Sources » Synced Objects and Fields** in Spiff, scroll to the Webhook connector, and select a mapping. The ID is visible under the mapping name. * `company_uuid` (query, string (guid)) Unique identifier for your company in Spiff. This query parameter is optional. We recommend including it with every request. To find this value, go to **Admin » Settings » Company Settings** in Spiff and copy the **Company UUID** at the top of the page. _Example_ ``` e3804275-aba4-4581-ac23-5b195b1a5f52 ``` * `signature` (header, string, required) HMAC-SHA256 cryptographic hash of the current time, the request body, and the webhook secret that you generate in Spiff. 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. See [Get Started with Salesforce Spiff Webhook API](/docs/sales/spiff/guide/webhook-api-get-started.html). Example: `t=1750092638,v1=d79efcece486e8de2f0384b9b07f2af6cd5859685489f6c1fd71be`. #### Request body Media type: `application/json`. Schema: `array of string`. Array of `string`. _Example: users\_delete\_example_ user ``` [ { "external_id": "12345" }, { "external_id": "67890" } ] ``` #### Responses * **200** The request was successful. Media type: `application/json`. Schema: `object`. * `ok` (_boolean_) Example: `true`. * **400** The request was unsuccessful for one of these reasons: * Your endpoint URL is invalid. * The webhook doesn't have any mappings created. See [Get Started with Salesforce Spiff Webhook API](/docs/sales/spiff/guide/webhook-api-get-started.html). * **401** The request was unsuccessful because the HMAC-SHA256 signature is invalid. ### PUT testWebhook `PUT /connector/{connector_id}/test` Operation ID: `testWebhook`. Tests the HMAC-SHA256 signature authentication, but doesn't upsert any data. #### Parameters * `subdomain` (path, string, required) The subdomain for your Spiff environment. * If you're in the US, use `us1`. * If you're in the EU, use `eu1`. _Example_ ``` us1 ``` * `connector_id` (path, string, required) ID of the webhook connector for the third-party data source in Spiff. To find this ID, go to **Admin » Connectors** in Spiff, find the Webhook connector, click the three dots menu, and select **More Info**. The ID is visible in the Webhook Integration Information window. _Example_ ``` 149 ``` * `company_uuid` (query, string (guid)) Unique identifier for your company in Spiff. This query parameter is optional. We recommend including it with every request. To find this value, go to **Admin » Settings » Company Settings** in Spiff and copy the **Company UUID** at the top of the page. _Example_ ``` e3804275-aba4-4581-ac23-5b195b1a5f52 ``` * `signature` (header, string, required) HMAC-SHA256 cryptographic hash of the current time, the request body, and the webhook secret that you generate in Spiff. 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. See [Get Started with Salesforce Spiff Webhook API](/docs/sales/spiff/guide/webhook-api-get-started.html). Example: `t=1750092638,v1=d79efcece486e8de2f0384b9b07f2af6cd5859685489f6c1fd71be`. #### Request body Media type: `application/json`. Schema: `object`. _Example: user\_example_ user ``` { "external_id": "12345", "name": "Jane Doe", "email": "jane.doe@company.com" } ``` #### Responses * **200** The request was successful and the HMAC-SHA256 signature was generated correctly. Media type: `application/json`. Schema: `object`. * `ok` (_boolean_) Example: `true`. * **400** The request was unsuccessful for one of these reasons: * Your endpoint URL is invalid. * The webhook doesn't have any mappings created. See [Get Started with Salesforce Spiff Webhook API](/docs/sales/spiff/guide/webhook-api-get-started.html). * **401** The request was unsuccessful because the HMAC-SHA256 signature is invalid.