Developing Optacy Webhooks

Event types, example payloads, and field reference for Optacy privacy request webhooks.

Optacy currently supports two events:

privacy_request.received
privacy_request.updated

Both carry the latest state of the privacy request. For a toll-free number (voicemail) request, you may receive two privacy_request.updated events after receipt: one when the recording is available, and another when transcription is ready.

Example: privacy_request.received (webform)

{
  "event_name": "privacy_request.received",
  "signature": {
    "random_token": "b39a5c7ac85ec479f921cdfaae4b4eee",
    "timestamp": "1584300477293",
    "signature": "599a40fb2d25f995a40dc43f725a57be4e8df90"
  },
  "id": "4e2c7dcd-8277-40bb-1082-66c7cb417df2",
  "type": "WebForm",
  "primary_identifier": "john@doe.com",
  "consumer_email": "john@doe.com",
  "email_verified_at": "2025-01-01",
  "acknowledged": true,
  "categorized": false,
  "verified": false,
  "extended": false,
  "completed": false,
  "completed_rights": {
    "data_categories_request": { "completed": false, "completed_at": null },
    "do_not_sell": { "completed": true, "completed_at": "2025-01-01" },
    "erase_my_information": { "completed": false, "completed_at": null },
    "send_me_a_copy_of_information": { "completed": false, "completed_at": null },
    "other": { "completed": false, "completed_at": null }
  },
  "deadline": "2025-07-02",
  "created_at": "2025-05-18T17:36:44.399Z",
  "updated_at": "2025-05-18T17:36:45.187Z",
  "categorized_country": "USA",
  "categorized_state": "California",
  "service_code": {
    "code": 1,
    "name": "Example Brand",
    "created_at": "2024-07-16T20:31:24.915Z",
    "updated_at": "2025-05-18T16:40:19.894Z"
  },
  "jurisdiction_rule": {
    "name": "USA only",
    "description": "Description of applied Jurisdiction Rule",
    "created_at": "2025-05-17T18:48:59.391Z",
    "days_to_process": 45,
    "notes": "Available in the Jurisdictions tab in the dashboard."
  },
  "web_form_session": {
    "id": "904c1b30-2ba8-49cf-a349-46f7c6b29e70",
    "created_at": "2025-05-18T17:36:44.394Z",
    "remote_ip": "24.102.96.226"
  }
}

Example: privacy_request.updated (voicemail)

{
  "event_name": "privacy_request.updated",
  "signature": {
    "random_token": "a021778c09cdae8897859340d3f0b32f",
    "timestamp": "1584305606907",
    "signature": "201de4703b7ce1eb33878fa29d77d8572ddeb2af"
  },
  "id": "abf78bbb-a152-4f09-90ad-5802f53721d7",
  "type": "Voicemail",
  "primary_identifier": "john@doe.com",
  "consumer_email": "john@doe.com",
  "acknowledged": false,
  "categorized": false,
  "verified": true,
  "extended": false,
  "completed": true,
  "deadline": "2019-11-05",
  "created_at": "2019-09-21 16:31:11 UTC",
  "updated_at": "2020-03-15 20:48:05 UTC",
  "categorized_country": "USA",
  "categorized_state": "California",
  "service_code": {
    "code": "2",
    "name": "test",
    "created_at": "2019-09-21 16:31:11 UTC",
    "updated_at": "2020-01-26 05:59:40 UTC"
  },
  "call_session": {
    "created_at": "2019-09-21 16:31:11 UTC",
    "ended_at": "2019-09-21 16:33:11 UTC",
    "caller_id": "+15555555555",
    "caller_name": "John Smith",
    "caller_state": "CA",
    "recording_status": "completed",
    "mp3_encoded_bytes": "",
    "transcription_status": "completed",
    "transcription_text": "Hello world!"
  }
}

Privacy request fields

Key	Description
`event_name`	String, e.g. `privacy_request.received`
`signature`	Object with random token, timestamp (ms), and signature (see Software Security)
`id`	UUID of the privacy request
`type`	String, e.g. `Voicemail` or `WebForm`
`primary_identifier`	Primary identifier for the request
`consumer_email`	Email used to communicate with the requester
`email_verified_at`	When the email was verified
`acknowledged`	Whether the request was acknowledged
`verified`	Whether the request is marked verified
`categorized`	Whether the request is categorized (always true for webform)
`completed`	Whether the request was completed
`completed_rights`	Map of right keys to `{ completed, completed_at }`
`extended`	Whether the deadline was extended
`deadline`	Due date from Jurisdiction Rules, extensions, and unfinished rights
`created_at` / `updated_at`	Request timestamps
`categorized_rights`	Preferred rights view: answers plus right configuration
`categorized_questions_data`	Preferred form answers view: values plus Form Field Set config
`categorized_country` / `categorized_state`	Preferred jurisdiction fields (`state` null outside the US)

Service Code

Key	Description
`code`	Service Code for this request
`name`	Service Code display name
`created_at` / `updated_at`	Service Code timestamps

Call session (toll-free number requests)

Key	Description
`created_at` / `ended_at`	Call start and hang-up times
`caller_id`	Caller phone number
`caller_name`	CNAM lookup name
`caller_state`	US state from area code when available
`recording_status`	`completed` when bytes are available, or `failed`
`mp3_encoded_bytes`	Base64-encoded MP3 bytes
`transcription_status`	`completed` when transcription is ready
`transcription_text`	Transcription text

Web form session

Key	Description
`id`	Web form session UUID
`created_at`	When the webform was received
`remote_ip`	Requester IP address
`webform_questions_data` / `rights`	Prefer `categorized_questions_data` and `categorized_rights` instead
`country_of_residence` / `state`	Copied into categorized country/state fields