Version: 2025-12-18

Understanding webhook event notifications

Webhooks are automated messages sent from an application (like Cint Exchange) to a specified destination URL when a particular event occurs. Unlike traditional API polling (where you constantly ask for updates), webhooks push information to you instantly as events happen. Cint leverages webhooks to notify customers about significant change events across their market research projects.

Why use webhooks?

Cint webhooks are designed to provide actionable insights, enabling you to:

Monitor target groups: Gain real-time visibility into the status and performance of your live surveys.
Automate Actions: Trigger automated processes within your system in response to changes.
Alert internal teams: Automatically notify relevant stakeholders when they need to review or make adjustments to a target group.

Core webhook streams

Cint currently provides information through the following webhook event streams:

Webhook	Focus	Value	Use case examples
Sessions data	The complete respondent lifecycle within a survey.	Granular updates on individual respondents, including their entry into the survey, status changes (e.g., complete, terminate), time spent, and any issues encountered during their journey.	Real-time respondent tracking, reconciliation verification, and detailed individual session analysis.
Demand changelog	Configuration and status changes to your target groups.	Notifications whenever a target group is created, modified (e.g., changes to its name, URLs, budget), or undergoes a status change (e.g., launched, paused). Includes information on who initiated the change (user ID or automation).	Synchronizing target group states with your internal systems and reacting to configuration updates.
Quota fill	Progress on your survey's quotas.	Real-time data on the number of screens (respondents who enter a profile screen) and completes achieved for specific quotas within your target groups.	Monitoring survey progress, triggering over-quota redirects, and managing fieldwork pacing.

info

You can retrieve a list of the specific events you are subscribed to or manage your webhook subscriptions via the notifications webhooks endpoint.

Example subscribed events response:

{
  "webhooks": [
    {
      "id": "e8e705b9-ef5a-437c-873a-4f49a679f802",
      "url": "https://example.com/target-group-updated-webhook",
      "event": [
        "target-group-updated"
      ],
      "created_at": "2023-01-01T23:00:00.000Z",
      "updated_at": "2023-01-01T23:00:00.000Z"
    },
    {
      "id": "3fda1b8d-bf76-4f38-bddb-8734cbec553f",
      "url": "https://example.com/quota-fill-registered-webhook",
      "event": [
        "quota-fill-registered"
      ],
      "created_at": "2023-01-01T23:00:00.000Z",
      "updated_at": "2023-01-01T23:00:00.000Z"
    }
  ],
  "has_more": true
}

Webhook event structure

Cint's webhooks adhere to the CloudEvents v1.0.2 specification. This industry-standard format ensures consistency and simplifies event processing for consumers. Every webhook payload you receive is encapsulated within a CloudEvents envelope.

CloudEvents envelope

The CloudEvents envelope provides a standardized set of metadata fields common to all event types. This layer promotes interoperability and allows your systems to process fundamental event information predictably, regardless of the specific data payload.

Field	Type / Format	Description	Example
`id`	String / UUID	Unique identifier for this specific event instance.	`b00ad4d6-a477-4d7c-abcf-90558ffef804`
`specversion`	String	The CloudEvents specification version (always `1.0`).	`1.0`
`source`	URI	A URI identifying the producer of the event (Cint).	`https://api.cint.com`
`type`	String	The specific type of event (e.g., `com.cint.target-group.updated`).	`com.cint.target-group.updated`
`time`	Date time / RFC3339	ISO 8601 timestamp indicating when the event occurred (UTC).	`2025-02-13T11:39:49.274Z`
`datacontenttype`	String	The format of the `data` payload (always `application/json`).	`application/json`
`dataschema`	URI	A URI referencing the JSON Schema for the `data` payload.	`https://schemas.cint.com/v1/session-updated.json`

Event-specific payload (`data` field)

The data field within the CloudEvents envelope holds the actual event payload. The structure of this data object varies depending on the type of event. Each data object is defined and validated against a dedicated JSON Schema, ensuring its predictability.

Example response:

{
  "id": "b00ad4d6-a477-4d7c-abcf-90558ffef804",
  "specversion": "1.0",
  "source": "https://api.cint.com",
  "type": "com.cint.target-group.updated",
  "time": "2025-02-13T11:39:49.274Z",
  "datacontenttype": "application/json",
  "dataschema": "https://schemas.cint.com/v1/session-updated.json",
  "data": {
    // The payload based on type field
  }
}

Detailed webhook payloads

Here are the structures for the data field for each of the primary webhook types:

1. Sessions data webhook payload (`type: com.cint.session.updated`)

This payload provides granular details about individual respondent sessions.

Field	Type / Format	Description	Example
`account_id`	Integer	The unique ID of the account.	`1`
`response_session_id`	String / UUID	Unique identifier for the respondent's session.	`67adda00-f3a4-f7b3-4dd2-f8494c3d5017`
`sequence_number`	Integer	A sequential number for events within a session, indicating order.	`5`
`project_id`	String / ULID	The unique ID of the project the session belongs to.	`01JH2Q9824364JXCT9R8HDKKR8`
`target_group_id`	String / ULID	The unique ID of the target group the session belongs to.	`01BX5ZZKBKACTAV9WEVGEMMVS1`
`survey_id`	Integer	The ID of the survey.	`491982`
`supplier_id`	Integer	The ID of the supplier providing the respondent.	`18`
`supplier_name`	String	The name of the supplier.	`Supplier Name`
`respondent_id`	Integer	The unique numeric ID assigned to the respondent by Cint.	`147376725`
`respondent_entry_date`	Date time / RFC3339	Timestamp when the respondent entered the survey.	`2018-04-11T16:25:54.416Z`
`panelist_id`	String / UUID	The unique ID of the panelist.	`97d0fb32-f5d2-4897-8caa-e6e083bf82bf`
`parent_sid`	String / UUID	The parent session ID, if applicable (e.g., for multi-part surveys).	`"674859c3-692a-427d-4e99-6addc5e705f0"`
`entry_type`	Integer	Type of entry (e.g., `1` for direct entry).	`1`
`mid`	String	A unique identifier related to the marketing or campaign ID.	`Targeted`
`changes`	Array of Objects	Details specific changes that occurred during this event.	See `Change Objects` below

Example sessions data payload:

{
  "account_id": 1,
  "response_session_id": "67adda00-f3a4-f7b3-4dd2-f8494c3d5017",
  "sequence_number": 5,
  "project_id": "01JH2Q9824364JXCT9R8HDKKR8",
  "target_group_id": "01BX5ZZKBKACTAV9WEVGEMMVS1",
  "survey_id": 491982,
  "supplier_id": 18,
  "supplier_name": "Supplier Name",
  "respondent_id": 147376725,
  "respondent_entry_date": "2018-04-11T16:25:54.416Z",
  "panelist_id": "97d0fb32-f5d2-4897-8caa-e6e083bf82bf",
  "parent_sid": "674859c3-692a-427d-4e99-6addc5e705f0",
  "entry_type": 1,
  "mid": "Targeted",
  "changes": [
    {
      "object": "respondent_last_date_change",
      "new_value": "2025-02-13T11:39:49.274Z"
    },
    {
      "object": "client_status_code_change",
      "new_value": 1
    }
  ]
}

Sessions data change objects (changes.object values):

These strings indicate what specific aspect of the session was updated:

respondent_last_date_change
client_status_code_change
client_query_string_change
redirect_url_change
exchange_status_code_change
is_live_change

2. Demand changelog webhook payload (`type: com.cint.target-group.updated`)

This payload captures modifications and status changes to target groups.

Field	Type / Format	Description	Example
`id`	String / UUID	Unique identifier for this specific changelog event.	`ef4b7ed0-7408-4646-8750-cc6a33a3375a`
`account_id`	Integer	The unique ID of the account.	`1`
`project_id`	String / ULID	The unique ID of the project the target group belongs to.	`01JH2Q9824364JXCT9R8HDKKR8`
`target_group_id`	String / ULID	The unique ID of the target group that was changed.	`01BX5ZZKBKACTAV9WEVGEMMVS1`
`occurred_at`	Date time / RFC3339	Timestamp when the change occurred (UTC).	`2025-02-13T11:39:49.274Z`
`user`	Object	Details about the user or system that initiated the change.	See `User Object` below
`changes`	Array of Objects	An array describing the specific attributes that were changed.	See `Change Objects` below

Demand changelog user object (user fields):

type (string): The type of user (e.g., "las_user" for a Cint user, or could indicate an API token).
las_user_id (string / GUID): The unique ID of the user who made the change.

Example demand changelog payload:

{
  "id": "ef4b7ed0-7408-4646-8750-cc6a33a3375a",
  "account_id": "1",
  "project_id": "01JH2Q9824364JXCT9R8HDKKR8",
  "target_group_id": "01BX5ZZKBKACTAV9WEVGEMMVS1",
  "occurred_at": "2025-02-13T11:39:49.274Z",
  "user": {
    "type": "las_user",
    "las_user_id": "9fdf41e9-cbcc-43da-abe4-8a5d45eafd70"
  },
  "changes": [
    {
      "object": "filling_goal_change",
      "new_value": 110
    },
    {
      "object": "live_url_change",
      "new_value": "https://example.com/test1"
    }
  ]
}

Demand changelog change objects (changes.object values):

These strings indicate what specific attribute of the target group was updated:

name_change
external_name_change
collects_pii_change
business_unit_change
study_type_change
project_manager_change
filling_goal_change
filling_strategy_change
expected_length_of_interview_minutes_change
expected_incidence_rate_change
industry_lockout_code_change
cpi_note_change
cpi_change
live_url_change
test_url_change
status_change
currency_change
locale_change
project_id_change
pricing_assistance_change
pricing_dynamic_total_budget_change
pricing_dynamic_maximum_cpi_change
pricing_dynamic_minimum_cpi_change
pricing_dynamic_unlock_max_budget_usage_change
pricing_rate_card_maximum_cpi_change
quota_overlay_assisted_change
quota_overlay_balance_fill_change
quota_overlay_prevent_overfilling_change
pacing_assistance_change
pacing_adaptive_increment_interval_change
pacing_linear_increment_interval_change
soft_launch_assisted_change
soft_launch_demographics_strictness_percentage_change
soft_launch_filling_goal_percentage_change
soft_launch_end_date_change
fielding_period_start_date_change
fielding_period_end_date_change

3. Quota fill webhook payload (`type: com.cint.quota.fill.registered`)

This payload provides updates on the progress towards fulfilling your quotas.

Field	Type / Format	Description	Example
`account_id`	Integer	The unique ID of the account.	`1`
`target_group_id`	String / ULID	The unique ID of the target group being updated.	`01JPSECBPA847DD89PN9ZFFBE1`
`screens`	Integer	The current number of respondents who have screened in.	`113`
`completes`	Integer	The current number of completed interviews.	`73`
`profile_quota_id`	String / ULID	The unique ID of the specific profile quota that was updated (if applicable).	`01JPSECY0CC2XAJEP5EV18SD9F`

Example quota fill payload:

{
  "account_id": 1,
  "target_group_id": "01JPSECBPA847DD89PN9ZFFBE1",
  "screens": 113,
  "completes": 73,
  "profile_quota_id": "01JPSECY0CC2XAJEP5EV18SD9F"
}

Why use webhooks?​

Core webhook streams​

Webhook event structure​

CloudEvents envelope​

Event-specific payload (data field)​

Detailed webhook payloads​

1. Sessions data webhook payload (type: com.cint.session.updated)​

2. Demand changelog webhook payload (type: com.cint.target-group.updated)​

3. Quota fill webhook payload (type: com.cint.quota.fill.registered)​