Webhooks

Subscription Configuration

Webhook subscriptions are managed exclusively through the Auvious Application Settings UI, with each subscription directly associated with a specific Application. Organizations can create multiple applications, each maintaining independent webhook subscriptions, enabling granular integration strategies.

Endpoint Configuration

Base URL: One endpoint URL per subscription. Auvious sends webhook notifications to this endpoint via HTTP POST requests.

Authentication Options

Auvious supports multiple authentication methods to secure webhook communications:

No Authentication: Requests sent without authentication headers.
HTTP Basic Authentication: Requires valid username/password credentials.
OAuth2 Client Credentials: Requires correct configuration of:
- Client ID
- Client Secret
- Access Token URL

Credentials must be validated and operational to ensure successful authentication.

HMAC Signature (Required)

All webhook notifications require an HMAC key. Organizations may provide their custom key or generate one via Auvious. This key generates an HMAC-SHA256 signature from the webhook payload, included in the x-signature HTTP header to verify the authenticity and integrity of requests.

Webhook Security and HMAC Verification

Auvious webhook notifications are securely delivered using an HMAC-SHA256 signature. This ensures the authenticity and integrity of the payloads your systems receive.

How It Works

Each webhook request from Auvious includes an x-signature HTTP header.
The signature is generated by Auvious using the webhook payload and a shared secret key (configured per subscription).
Customers verify authenticity by computing an HMAC-SHA256 hash of the received payload using the shared secret and comparing it to the x-signature header value.

Recommended Verification Steps

Retrieve the payload from the HTTP POST request sent by Auvious.
Extract the x-signature header from the request.
Compute your own HMAC signature using:
- SHA256 hashing algorithm.
- Your webhook subscription’s shared secret key.
- The raw webhook payload (exactly as received).
Compare the computed signature with the received x-signature value:
- If signatures match, the payload is authentic and unaltered.
- If they do not match, the payload should be considered invalid or compromised.

Key Benefits

Security: Guarantees the webhook payload has not been tampered with during transmission.
Authenticity: Confirms payloads are genuinely sent by Auvious and not a third party.
Standardized: Easily implementable across most platforms and frameworks.

Webhook Headers & Metadata

Auvious webhook notifications provide robust flexibility and integration capabilities through customizable headers and metadata fields, supporting diverse and secure integration scenarios.

Key Header Types

Custom Headers (customHeaders)

Subscription-level configuration: Defined once per webhook subscription.
Header types supported:
- DEFAULT: Static, non-sensitive headers included in every webhook request.
- SECRET: Sensitive headers stored securely, obfuscated, and masked in all interfaces to protect confidentiality.
Ideal for securely including static authentication tokens or API keys in webhook requests.

Notification Headers (notificationHeaders)

Configured per appointment: Defined within each appointment request.
Dynamically forwarded in webhook notifications.
Useful for context-specific tracking or identifying the originating source or channel of each notification.

Metadata (metadata)

Appointment-specific custom data: Included within each appointment request and transmitted directly in webhook payloads.
Facilitates dynamic integration scenarios, such as passing through customer identifiers, CRM information, or custom tracking parameters.
Enhances context-awareness and data richness in downstream integrations.

Security Best Practices:

Avoid transmitting highly sensitive data in headers, as they can be intercepted if webhooks are improperly secured.
Auvious always secures webhook notifications using an HMAC-SHA256 signature in the x-signature header, generated from the webhook payload.
It is strongly recommended that receivers verify this HMAC signature to ensure the authenticity and integrity of incoming webhook notifications.

Implementing these features and following recommended security practices ensures robust, secure, and flexible integration of Auvious webhooks with your systems.

Webhook Notification Delivery Model

Webhook notifications employ a single-endpoint, stateless delivery model:

Single Endpoint: Notifications are consistently sent via HTTP POST to the subscriber-defined endpoint URL.
Stateless Payload: Each notification payload is entirely self-contained, delivering complete context without relying on external or prior state.

Payloads explicitly include:

An event type (type) clearly defining the event nature.
Comprehensive event-specific data.
ChangeContext when applicable (for changes or updates).

Webhook Notification Types

Webhook notifications are sent by Auvious to inform integrated systems of key events during the lifecycle of appointments. Below is a clear overview of available notifications, their triggers, and descriptions.

Notification Types Summary

Type	Trigger	Description
APPOINTMENT_CREATED	Immediately upon scheduling an appointment.	Triggered when a new appointment is created.
APPOINTMENT_RESCHEDULED	When the schedule (start/end time or timezone) changes.	Triggered whenever the appointment’s schedule details are updated.
APPOINTMENT_IN_PROGRESS	When the first participant (agent or customer) joins the call.	Triggered when the appointment transitions to the “In Progress” state.
APPOINTMENT_COMPLETED	After all participants leave, or the appointment concludes normally.	Indicates the appointment has successfully ended.
APPOINTMENT_CANCELLED	When explicitly cancelled by a user or the system.	Triggered upon explicit cancellation of the appointment.
APPOINTMENT_NO_SHOW	Scheduled end time passes without anyone joining.	Triggered when an appointment expires without attendance.
APPOINTMENT_UPDATED	When metadata or details (excluding schedule) are updated.	Triggered upon changes to appointment metadata such as title, notes, or custom properties.
APPOINTMENT_REMINDER	At predefined intervals before appointment start.	Sent as a reminder at configured intervals before the appointment begins.
APPOINTMENT_FOLLOWUP	At predefined intervals after the appointment is successfully completed.	Triggered post-appointment to prompt follow-up actions, feedback, or summaries.
PARTICIPANT_ADDED	When a participant is newly added to the appointment.	Indicates a new participant has been included in the appointment.
PARTICIPANT_REMOVED	When a participant is explicitly removed from the appointment.	Indicates removal of an existing participant. (Note: Removed participant receives a cancellation notification.)
PARTICIPANT_UPDATED	When a participant's personal details (e.g., contact info) change.	Triggered whenever participant details like email, phone, or custom fields are updated.
INTERACTION_UPDATED	When interaction details (e.g., routing, queues) change before or during the call.	Indicates updates to interaction-specific details before or during the appointment.

Important Notes for Integrators

Notifications reflect explicit domain events: Each notification corresponds to specific state changes or actions in the appointment lifecycle.
Configurable intervals: Reminder and Follow-up notifications use configurable offsets before and after the appointment.
Security and reliability: All notifications include an HMAC signature for secure verification.

Auvious Webhook Notification Payload Reference

Auvious webhook notifications are delivered as HTTP POST requests with JSON payloads. Each payload contains comprehensive and self-contained information about appointment-related events.

Common Webhook Structure

All webhook notifications share this common top-level structure:

Field	Type	Description
id	string	Unique identifier for the webhook event.
type	string	Event type identifier (e.g., `APPOINTMENT_CREATED`).
timestamp	string (ISO8601)	UTC timestamp of when the event was emitted.
payload	object	Event-specific data (see details below).

AppointmentBasePayload (Included in all Appointment Notifications)

Every appointment-related payload includes an embedded AppointmentBasePayload object, which contains essential appointment details:

Field	Type	Description
appointmentId	string	Unique identifier for the appointment.
organizerId	string	Identifier of the appointment organizer.
applicationId	string	Identifier of the associated application.
organizationId	string	Identifier of the associated organization.
schedule	object (`Schedule`)	Appointment scheduling details.
metadata	object (`Metadata`)	Custom appointment metadata (title, notes, custom fields).
participants	array (`Participant`)	List of participants associated with the appointment.
interactionData	object (`InteractionData`)	Interaction routing and custom fields.
sentAt	string (ISO8601)	Timestamp of the event occurrence.

🔸 Schedule Object

Field	Type	Description
startTime	string (ISO8601)	Appointment start time (UTC).
endTime	string (ISO8601)	Appointment end time (UTC).
duration	string (ISO8601 duration)	Duration (e.g., `"PT30M"`).
timeZone	string	Timezone identifier (e.g., `"Europe/Athens"`).
locale	string	Locale identifier (e.g., `"en-US"`).

🔸 Metadata Object

Field	Type	Description
title	string (optional)	Appointment title.
notes	string (optional)	Additional appointment notes.
customFields	object/map (optional)	Custom key-value pairs (appointment-specific data).

🔸 Participant Object

Field	Type	Description
id	string	Unique participant identifier.
type	string	Participant role (`CUSTOMER`, `AGENT`, or `CLIENT_SERVICE`).
username	string (optional)	Username (typically an email address).
name	object (`Name`)	First and last names.
contact	object (`Contact`)	Primary phone and email.
metadata	object/map (optional)	Additional participant metadata.
ticket	object (`Ticket`, optional)	Access-related details (URL, validity, access type).

Name Object

Field	Type	Description
firstName	string	Participant’s first name.
lastName	string	Participant’s last name.

Contact Object

Field	Type	Description
primaryPhone	string	Primary contact phone number.
primaryEmail	string	Primary contact email address.

Ticket Object (optional)

Field	Type	Description
url	string (URL)	URL for participant access.
validUntil	string (ISO8601)	Ticket validity expiration time.
accessType	string	Access type (`SINGLE_USE_ACCESS`, `MULTI_USE_ACCESS`).

🔸 InteractionData Object

Field	Type	Description
routing	object (`RoutingData`, optional)	Routing configuration data.
customFields	map/object (optional)	Additional interaction-specific fields.

RoutingData Object

Field	Type	Description
type	string	Routing type (e.g., GenesysCloudFlow).
properties	map/object	Routing-specific key-value properties.

Field	Type	Description
systemMessage	string	Technical/system-level error message.
userMessage	string	User-facing descriptive error message.

🔸 ChangeContext Object (Update-type payloads only)

Field	Type (`optional`)	Description
previousSchedule	object (`Schedule`)	Previous schedule details (before the change).
previousMetadata	object (`Metadata`)	Previous metadata (before update).
previousInteractionData	object (`InteractionData`)	Previous interaction data (before update).
addedParticipant	object (`Participant`)	Newly added participant details.
removedParticipant	object (`Participant`)	Details of removed participant.
previousParticipant	object (`Participant`)	Participant details prior to an update.
errorData	object (`InteractionError`)	Error details associated with event (if applicable).

Notification Payload Types (Examples)

Recommended Implementation Steps for Integrators

Implement secure HTTPS endpoints to receive webhook notifications.
Parse JSON payloads according to the provided event structures.
Validate incoming HMAC signatures (x-signature header) before processing payloads.
Respond with appropriate HTTP status codes (2xx for successful processing, 4xx/5xx for errors).
Use the detailed payload information to integrate seamlessly with downstream services or processes.

Security Recommendations

Although Auvious provides flexible custom-header authentication, we strongly recommend against transmitting sensitive data within webhook headers due to interception risks. Additionally:

Always secure webhook endpoints using HTTPS to further mitigate interception threats.

Auvious secures webhook payloads through robust verification using HMAC-SHA256 signatures:

Each webhook includes an HMAC-SHA256 signature (x-signature header) generated using your configured HMAC secret key.
Integrators should verify authenticity by:
1. Computing an HMAC-SHA256 hash of the received payload.
2. Comparing it with the Auvious-provided x-signature header.
3. Accepting notifications only when signatures match.

This widely-supported practice ensures payload authenticity and integrity, significantly enhancing security.

Benefits Summary

Auvious webhook subscriptions and notifications offer:

Unified Single Endpoint: Simplified integration.
Stateless Processing: Robust, self-contained payloads for reliable event handling.
Enhanced Security: Multiple authentication methods, mandatory HMAC signature verification, and masked sensitive headers.
Flexible Integration: Comprehensive header and metadata customization for varied use-cases.
Reliable Tracking: Clearly defined delivery protocols and upcoming retry mechanisms to enhance reliability.

This robust, secure, and highly adaptable webhook model is designed to meet diverse organizational integration needs effectively.

Webhook Notification Payload Reference Types

Webhook Event Types

📅 Appointment Created

Triggered when a new appointment is scheduled.

Includes:

Appointment details (schedule, metadata, participants, interaction information).

🗓️ Appointment Rescheduled

Triggered upon changes to an existing appointment's schedule.

Includes:

Appointment details.
Previous schedule details for comparison (oldSchedule).

⏳ Appointment In Progress

Triggered when an appointment becomes active (participant joined).

Includes:

Appointment details.

✅ Appointment Completed

Triggered upon successful completion of an appointment.

Includes:

Appointment details.

❌ Appointment Cancelled

Triggered when an appointment is explicitly cancelled.

Includes:

Appointment details.
Optional cancellation reason (reason).

🚫 Appointment No-Show

Triggered when an appointment expires without attendance.

Includes:

Appointment details.

✏️ Appointment Updated

Triggered when metadata or details of an appointment are modified.

Includes:

Appointment details.
Previous metadata (oldMetadata) for comparison.

⏰ Appointment Reminder

Triggered as a reminder at configured intervals before an appointment begins.

Includes:

Appointment details.

📩 Appointment Follow-Up

Triggered after the appointment ends, prompting participants for feedback or additional actions.

Includes:

Appointment details.

➕ Participant Added

Triggered when a new participant is added to an existing appointment.

Includes:

Appointment details.
Newly added participant details (addedParticipant).

➖ Participant Removed

Triggered when a participant is removed from an appointment.

Includes:

Appointment details.
Removed participant details (removedParticipant).

🔄 Participant Updated

Triggered when details of an existing participant (e.g., contact info) are changed.

Includes:

Appointment details.
Updated participant details (updatedParticipant).

💬 Interaction Updated

Triggered when interaction-specific details such as routing or queue properties are changed.

Includes:

Appointment details.
Previous interaction data (oldInteractionData) for reference.

Webhook Notification Payload Example

Below is an example JSON payload illustrating the structure of an APPOINTMENT_UPDATED webhook notification from Auvious:

Example: Appointment Updated (`APPOINTMENT_UPDATED`)

{
  "id": "b3a1c2e0-8a4f-4f2b-95f6-7123ef5b4c67",
  "type": "APPOINTMENT_UPDATED",
  "timestamp": "2025-07-10T10:45:22.064Z",
  "payload": {
    "appointmentId": "d2f14c97-c4b2-43e2-baad-0123abc4d567",
    "organizerId": "9a8c1f20-1111-4c3b-8888-4567efab7890",
    "applicationId": "123abcde-6789-4321-abcd-ef5678901234",
    "organizationId": "myorg.example_12345abc-def6-7890-gh12-ijklmno34567",
    "startTime": "2025-07-15T09:00:00.000Z",
    "endTime": "2025-07-15T09:30:00.000Z",
    "duration": "PT30M",
    "timeZone": "Europe/Athens",
    "locale": "en-US",
    "title": "Quarterly Sales Review",
    "notes": "Discuss updated sales targets and regional performance.",
    "customFields": {
      "meetingType": "Quarterly Business Review"
    },
    "participants": [
      {
        "id": "9a8c1f20-1111-4c3b-8888-4567efab7890",
        "type": "AGENT",
        "username": "jsmith@myorg.example.com",
        "name": {
          "firstName": "John",
          "lastName": "Smith"
        },
        "contact": {
          "primaryEmail": "jsmith@myorg.example.com"
        },
        "metadata": {
          "auviousUserId": "9a8c1f20-1111-4c3b-8888-4567efab7890",
          "avatarUrl": "https://example.com/profiles/avatar123.jpg",
          "organization_id": "12345abc-def6-7890-gh12-ijklmno34567",
          "user_id": "9a8c1f20-1111-4c3b-8888-4567efab7890"
        }
      },
      {
        "id": "5b6c7d8e-9f01-2345-6789-abcdef012345",
        "type": "CUSTOMER",
        "username": "customer123@example.com",
        "name": {
          "firstName": "Alice",
          "lastName": "Johnson"
        },
        "contact": {
          "primaryEmail": "alice.johnson@example.com"
        },
        "ticket": {
          "url": "https://app.auvious.video/q/abc-xyz",
          "validUntil": "2025-07-15T10:00:00.000Z",
          "accessType": "SINGLE_USE_ACCESS"
        }
      }
    ],
    "interactionData": {
      "routing": {
        "type": "GENESYS_CLOUD_QUEUE",
        "properties": {
          "agentId": "9a8c1f20-1111-4c3b-8888-4567efab7890",
          "chatMode": "genesys-cloud",
          "conferenceId": "12345678-90ab-cdef-1234-567890abcdef",
          "deploymentId": "abcdef12-3456-7890-abcd-ef1234567890",
          "pcEnvironment": "mypurecloud.de",
          "queueName": "Sales_Queue"
        }
      }
    },
    "sentAt": "2025-07-10T10:45:22.063Z",
    "changeContext": {
      "previousMetadata": {
        "title": "Monthly Sales Sync",
        "notes": "Monthly sync-up to review sales."
      }
    }
  }
}

Webhooks

Subscription Configuration​

Endpoint Configuration​

Authentication Options​

HMAC Signature (Required)​

Webhook Security and HMAC Verification​

How It Works​

Recommended Verification Steps​

Key Benefits​

Webhook Headers & Metadata​

Key Header Types​

Custom Headers (customHeaders)​

Notification Headers (notificationHeaders)​

Metadata (metadata)​

Security Best Practices:​

Webhook Notification Delivery Model​

Webhook Notification Types​

Notification Types Summary​

Important Notes for Integrators​

Auvious Webhook Notification Payload Reference​

Common Webhook Structure​

AppointmentBasePayload (Included in all Appointment Notifications)​

🔸 Schedule Object​

🔸 Metadata Object​

🔸 Participant Object​

Name Object​

Contact Object​

Ticket Object (optional)​

🔸 InteractionData Object​

RoutingData Object​

🔸 InteractionError Object (Only in failure-related payloads)​

🔸 ChangeContext Object (Update-type payloads only)​

Notification Payload Types (Examples)​

Recommended Implementation Steps for Integrators​

Security Recommendations​

Benefits Summary​

Webhook Notification Payload Reference Types​

Webhook Event Types​

📅 Appointment Created​

🗓️ Appointment Rescheduled​

⏳ Appointment In Progress​

✅ Appointment Completed​

❌ Appointment Cancelled​

🚫 Appointment No-Show​

✏️ Appointment Updated​

⏰ Appointment Reminder​

📩 Appointment Follow-Up​

➕ Participant Added​

➖ Participant Removed​

🔄 Participant Updated​

💬 Interaction Updated​

Webhook Notification Payload Example​

Example: Appointment Updated (APPOINTMENT_UPDATED)​

Subscription Configuration

Endpoint Configuration

Authentication Options

HMAC Signature (Required)

Webhook Security and HMAC Verification

How It Works

Recommended Verification Steps

Key Benefits

Webhook Headers & Metadata

Key Header Types

Custom Headers (customHeaders)

Notification Headers (notificationHeaders)

Metadata (metadata)

Security Best Practices:

Webhook Notification Delivery Model

Webhook Notification Types

Notification Types Summary

Important Notes for Integrators

Auvious Webhook Notification Payload Reference

Common Webhook Structure

AppointmentBasePayload (Included in all Appointment Notifications)

🔸 Schedule Object

🔸 Metadata Object

🔸 Participant Object

Name Object

Contact Object

Ticket Object (optional)

🔸 InteractionData Object

RoutingData Object

🔸 InteractionError Object (Only in failure-related payloads)

🔸 ChangeContext Object (Update-type payloads only)

Notification Payload Types (Examples)

Recommended Implementation Steps for Integrators

Security Recommendations

Benefits Summary

Webhook Notification Payload Reference Types

Webhook Event Types

📅 Appointment Created

🗓️ Appointment Rescheduled

⏳ Appointment In Progress

✅ Appointment Completed

❌ Appointment Cancelled

🚫 Appointment No-Show

✏️ Appointment Updated

⏰ Appointment Reminder

📩 Appointment Follow-Up

➕ Participant Added

➖ Participant Removed

🔄 Participant Updated

💬 Interaction Updated

Webhook Notification Payload Example

Example: Appointment Updated (`APPOINTMENT_UPDATED`)