Webhooks

• Applies to: Sprinklr Webhook Subscription API V3 (/api/v3/webhook-subscriptions)
• V2 API reference: Sprinklr Webhooks | Sprinklr Developer Portal

A webhook (also called a web callback or HTTP push API) enables third-party services to send real-time updates to your app. Updates are triggered by an event that occurs in Sprinklr, and the data is delivered to your endpoint immediately as it happens. Webhooks are also referred to as "Reverse APIs" — unlike typical APIs where you poll frequently for data, Sprinklr pushes the event to you, which is more efficient for both provider and consumer.

The Webhook Subscription API V3 manages the subscriptions that deliver those platform events to your endpoints. It supports listing and fetching, creating, updating, and deleting subscriptions, activating, deactivating, or verifying a subscription, and listing all webhook types.

V3 collapses the V2 endpoint family onto two paths plus one action path, differentiated by HTTP method and a query parameter:

1. Expose a callback URL. It must be publicly reachable and must answer a POST with an empty payload ({}) with a 2XX response. See §10 Callback URL verification check.
2. Create the subscription — POST /api/v3/webhook-subscriptions. A newly created subscription comes back with "verified": false and "active": false.
3. Verify it — POST /api/v3/webhook-subscriptions/action?subscriptionId=…&action=verify.
4. Activate it — POST /api/v3/webhook-subscriptions/action?subscriptionId=…&action=activate. Only then does Sprinklr start dispatching events.
5. Maintain it — update the subscribed types with PUT, pause delivery with action=deactivate, remove it with DELETE.

All API calls are sent to the production endpoint:

https://api3.sprinklr.com/{env}/api/v3

So the webhook subscription resource in production is:

https://api3.sprinklr.com/{env}/api/v3/webhook-subscriptions

Replace {env} with your assigned environment identifier (prod0, prod2, prod11, and so on — see APIs | Sprinklr Developer Portal for the environment list).

All Webhook Subscription API calls are authenticated with OAuth 2.0. See Developer Tools in Sprinklr for API key and secret generation, and the Authorize flow.

POST /api/v3/webhook-subscriptions

Creates a webhook subscription. The response returns the subscription id, which you need for every other operation. A new subscription is created with verified: false and active: false.

curl --location 'https://api3.sprinklr.com/{env}/api/v3/webhook-subscriptions' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "name": "My Webhook",
  "url": "https://mycallback.com",
  "preSharedKey": "{{preSharedKey}}",
  "subscriptions": [
    "CASE_CREATED"
  ]
}'

{
    "data": {
        "id": "6a1d7399e944edfa60817e9d",
        "name": "My Webhook",
        "subscriptions": [
            "CASE_CREATED"
        ],
        "filteredSubscriptions": [
            {
                "webhookType": "CASE_CREATED"
            }
        ],
        "url": "https://mycallback.com",
        "preSharedKey": "secret",
        "viaProxy": false,
        "verified": false,
        "active": false
    },
    "errors": []
}

Note that the platform echoes the flat subscriptions array back as a filteredSubscriptions entry with no filters — a subscription with no filters is equivalent to an unfiltered subscription on that type.

curl --location 'https://api3.sprinklr.com/{env}/api/v3/webhook-subscriptions' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "name": "API test",
  "description": "Webhook for case creation.",
  "subscriptions": [
    "CASE_CREATED"
  ],
  "filteredSubscriptions": [
    {
      "webhookType": "CASE_CREATED",
      "filters": [
        {
          "id": "ACCOUNT_TYPE",
          "type": "ACCOUNT_TYPE",
          "checkCondition": "IS",
          "values": [
            "Whatsapp_Business"
          ]
        }
      ]
    }
  ],
  "url": "https://mycallback.com",
  "preSharedKey": "{{preSharedKey}}"
}'

PUT /api/v3/webhook-subscriptions?subscriptionId={subscriptionId}

Updates the name, description, and subscribed webhook types of an existing subscription. The update is incremental on subscription types — you add and remove types rather than resubmitting the full list.

curl --location --request PUT 'https://api3.sprinklr.com/{env}/api/v3/webhook-subscriptions?subscriptionId=6a1e8c2d4adcdb00e372fc37' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "name": "vaibhav_api_4",
    "description": "updated the string",
    "addSubscriptions": [
        "CASE_CREATED"
    ],
    "removeSubscriptions": [
        "CASE_UPDATED"
    ]
}'

The response returns 204 No Content with an empty body.

DELETE /api/v3/webhook-subscriptions?subscriptionId={subscriptionId}

Deletes a Sprinklr webhook subscription.

curl --location --request DELETE 'https://api3.sprinklr.com/{env}/api/v3/webhook-subscriptions?subscriptionId=6a1d7399e944edfa60817e9d' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'

The endpoint returns 204 No Content on success.

POST /api/v3/webhook-subscriptions/action?subscriptionId={subscriptionId}&action={action}

Performs a lifecycle action on an existing subscription. This single V3 endpoint replaces the three separate V2 endpoints for verify, activate, and deactivate.

curl --location --request POST 'https://api3.sprinklr.com/{env}/api/v3/webhook-subscriptions/action?subscriptionId=6a0d7df617ab2359996fb225&action=verify' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'

{
    "data": true,
    "errors": []
}

data is true when the action succeeds, otherwise false.

Returns one subscription when subscriptionId is supplied, or a page of subscriptions when it is not. This single endpoint replaces the V2 Read Subscription and Read All Subscription endpoints.

curl --location 'https://api3.sprinklr.com/{env}/api/v3/webhook-subscriptions?subscriptionId=6a0d7df617ab2359996fb225' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'

{
    "data": [
        {
            "id": "6a0d7df617ab2359996fb225",
            "name": "SALESFORCE - Paris_test",
            "description": "Webhook subscription for SALESFORCE connector: Paris_test",
            "subscriptions": [
                "CASE_CREATED",
                "CASE_UPDATED"
            ],
            "filteredSubscriptions": [
                {
                    "webhookType": "CASE_CREATED",
                    "filters": [
                        {
                            "id": "6a0d7fa117ab23599970b714",
                            "type": "PARTNER_CUSTOM_PROPERTY",
                            "checkCondition": "IS",
                            "values": [
                                "DEV"
                            ]
                        }
                    ]
                },
                {
                    "webhookType": "CASE_UPDATED",
                    "filters": [
                        {
                            "id": "6a0d7fa117ab23599970b714",
                            "type": "PARTNER_CUSTOM_PROPERTY",
                            "checkCondition": "IS",
                            "values": [
                                "DEV"
                            ]
                        }
                    ]
                }
            ],
            "url": "https://qa6-std-connector-tier1.sprinklr.com/crm/SALESFORCE/6a0d7dc917ab2359996f90db?sprPartnerId=66000000",
            "viaProxy": false,
            "verified": true,
            "active": true,
            "lastSuccessTimestamp": 1779270302235
        }
    ],
    "errors": []
}

data is always an array on this endpoint, even when a single subscriptionId is requested.

Returns every webhook subscription type available in your environment. Use the returned type value in subscriptions[] or filteredSubscriptions[].webhookType when creating or updating a subscription. This endpoint takes no parameters.

curl --location 'https://api3.sprinklr.com/{env}/api/v3/webhook-subscriptions/webhook-types' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'

{
    "data": [
        {
            "type": "ACCOUNT_CREATED",
            "label": "Account Created Event",
            "category": "Account"
        },
        {
            "type": "CASE_CREATED",
            "label": "Case Created",
            "category": "Case"
        }
    ],
    "errors": []
}

Every V3 webhook subscription endpoint that returns a body returns the standard envelope:

{
  "data": [ ... ],
  "errors": []
}

400, 401, 403, and 404 are the four shared responses declared on all six operations in sprinklr-v3.yaml. No 429 or 5xx response is declared anywhere in the V3 specification.

The following 91 types across 32 categories were returned by GET /api/v3/webhook-subscriptions/webhook-types in the supplied collection. Available types are environment-dependent — always call the endpoint rather than hard-coding this list.

Event payload shapes for each type are documented on the V2 portal under Webhook Response Payloads. The payload contract is unchanged by the V3 subscription API — V3 changes how you manage subscriptions, not what Sprinklr posts to your callback URL.

1. GET /webhook-subscriptions/webhook-types — confirm CASE_CREATED and CASE_UPDATED are available.
2. POST /webhook-subscriptions with name, url, preSharedKey, and "subscriptions": ["CASE_CREATED","CASE_UPDATED"]. Store the returned id.
3. POST /webhook-subscriptions/action?subscriptionId={id}&action=verify — expect "data": true.
4. POST /webhook-subscriptions/action?subscriptionId={id}&action=activate.
5. GET /webhook-subscriptions?subscriptionId={id} — confirm "verified": true and "active": true.

Create the subscription with filteredSubscriptions instead of subscriptions, setting type to PARTNER_CUSTOM_PROPERTY, checkCondition to IS, and values to the property values you want, so only matching cases are dispatched. The GET example in §5.1 shows this shape on a live subscription.

PUT /webhook-subscriptions?subscriptionId={id} with "addSubscriptions": ["CASE_CREATED"]. Use removeSubscriptions in the same call to drop types you no longer want. There is no need to deactivate and recreate the subscription.

POST /webhook-subscriptions/action?subscriptionId={id}&action=deactivate while your consumer is down, then action=activate when it is back. Deactivating stops dispatch without losing the subscription configuration. For events missed while deactivated, see the Webhook Replay and Retrieve API — failed webhook events are retrievable for 7 days.

GET /webhook-subscriptions with no subscriptionId, paging with pageNumber and pageSize. Inspect lastSuccessTimestamp and lastFailedTimestamp on each record to find subscriptions whose endpoints have started failing.

No V3 operation updates url or preSharedKey on an existing subscription. Create a new subscription against the new URL, verify and activate it, confirm delivery, then DELETE the old one.

Callback URL verification check

• For any callback URL to work within a webhook subscription, a POST to that URL with an empty payload ({}) must return a 2XX response.
• Test it directly before calling action=verify:
  curl -X POST 'https://{Callback Url}' \
  --header 'Content-Type: application/json' \
  --data-raw '{}'

• The callback URL must be publicly reachable over the internet.

Webhook retries logic

• Sprinklr's webhook retries logic works on a count of 10 seconds. Once the webhook is triggered, Sprinklr waits 10 seconds to receive an HTTP 200 status code.
• If a webhook cannot be delivered successfully, it is retried three times through different queues (Queue 1 → Queue 2 → Queue 3) until the request receives a 200. Events that fail all three consecutive tries are stored in the Deleted Queue.
• The default 10-second window is unalterable — changing it would delay every webhook in the queue.
• Use an asynchronous webhook endpoint that returns 200 OK within 10 seconds. This avoids congestion at either the sender's or the receiver's end.

Payload signing

• The payload is signed with the preSharedKey using SHA-256 and added to the header X-Hub-Signature with the value sha256={sha256 digested payload using the preSharedKey}. Validate this signature on every inbound request.
• preSharedKey is required on create. Never log it or commit it.

Lifecycle

• A newly created subscription is verified: false and active: false. It dispatches nothing until it is verified and activated.
• verify and activate are separate actions — performing one does not perform the other.

Parameters

• subscriptionId on GET accepts comma-separated IDs; on PUT, DELETE, and /action supply exactly one.
• Do not wrap query values in braces. {6a0d7df617ab2359996fb225} is a Postman placeholder artifact, not a value format.
• pageNumber is 0-based and is typed as string in sprinklr-v3.yaml, as are pageSize and sinceTime.

Responses

• data is an array on GET /webhook-subscriptions even for a single-ID fetch.
• POST /webhook-subscriptions/action returns a boolean in data — true on success, false otherwise. Inspect it; a 200 alone does not prove the action succeeded.
• Always inspect the errors array even on a 200 response.

Authentication types

• The V3 create schema exposes only preSharedKey and viaProxy. The additional authentication types available in the Sprinklr UI — Salesforce, Public URL, Basic Auth, OAuth 2.0, External Authentication Credentials, and Marketplace Apps — have no representation in the V3 request schema. Configure those in the UI (see Create and Manage Webhook Subscription in Sprinklr)

Rate limiting and server errors

• No 429 or 5xx response is declared for these operations in sprinklr-v3.yaml. Implement retry with exponential backoff defensively rather than relying on the specification.