Webhooks

Webhooks let Auvious notify your systems about appointment lifecycle changes by sending HTTP POST requests to an endpoint you configure.

Subscription configuration

Webhook subscriptions are configured in the Auvious Application Settings UI and are associated with a specific Application. This allows different applications in the same organization to use different endpoints, credentials, and security settings.

Each subscription delivers webhook notifications to a single Base URL using HTTP POST.

Authentication

You can secure webhook delivery using one of the following authentication modes:

No authentication: Requests are sent without authentication headers.
HTTP Basic authentication: Auvious sends the configured username/password using HTTP Basic Auth.
OAuth2 client credentials: Auvious requests an access token from your Access Token URL using the configured Client ID and Client Secret, then includes the token in webhook requests (as a bearer token) according to the OAuth2 client-credentials flow.

Ensure the configured credentials are valid; otherwise webhook delivery will fail.

HMAC signature (required)

All webhook requests include an HMAC-SHA256 signature so your service can verify authenticity and detect tampering. Configure an HMAC key per subscription (you can provide your own or generate one in Auvious).

Auvious sends the signature in the x-signature HTTP header. To verify a request, compute HMAC-SHA256 over the exact payload value as delivered (the payload field content, without re-serializing or reformatting JSON), using the shared HMAC key, then compare your computed value with x-signature. Do not hash the full envelope (id, type, payload, timestamp). If the signature is missing or does not match, treat the request as invalid and do not process it.

Webhook Headers & Metadata

Webhooks can carry extra information in two places: HTTP headers and the JSON payload. Use headers for delivery-time context (for example, correlation IDs) and use metadata in the payload for appointment-specific information your integration needs.

Custom headers (customHeaders)

Custom headers are configured per webhook subscription and are included in every webhook request. Two types are supported: DEFAULT for static values, and SECRET for sensitive values that should not be displayed in plaintext in the UI.

Notification headers (notificationHeaders)

Notification headers are provided per appointment request and are forwarded on webhook delivery. They are useful for request-scoped correlation (for example, a tenant ID, tracking ID, or integration context).

Metadata (metadata)

Metadata is provided per appointment request and is included in the webhook payload. Use it for appointment-specific fields such as customer identifiers, CRM references, or custom integration attributes.

Security best practices

Prefer putting sensitive information in the payload rather than headers, and only include what your receiver actually needs. Every webhook includes an HMAC-SHA256 signature in the x-signature header; receivers should verify this signature before processing the event. Using authentication plus signature verification helps ensure events are authentic and reduces the risk of processing spoofed or tampered requests.

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_REASSIGNED	When the appointment is reassigned to a different agent/owner.	Emitted on reassignment.
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	When someone explicitly ends the appointment.	Indicates the appointment has ended normally.
APPOINTMENT_NO_SHOW	Scheduled end time passes without anyone joining.	Triggered when an appointment expires without attendance.
APPOINTMENT_FAILED	When the system cannot progress the appointment (e.g., setup errors).	Emitted on platform-level failure.
APPOINTMENT_CANCELLED	When explicitly cancelled by a user or the system.	Triggered upon explicit cancellation of the appointment.
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 (one-minute tolerance; not replayed).	Sent as a reminder at configured intervals before the appointment begins.
APPOINTMENT_FOLLOWUP	After the appointment completes successfully, only to customers who actually joined.	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.
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

Participant-added/removed/updated are emitted; participant-failed exists in code but is not emitted today.
ROOM/invite notifications are not emitted on webhooks (APPOINTMENT_INVITE is unsupported).
Reminder and follow-up windows are not replayed if missed; pending reminders/invites are cancelled when the call starts or is rescheduled.
APPOINTMENT_COMPLETED fires when someone ends the appointment; if no one joins, APPOINTMENT_NO_SHOW is sent instead.
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​

Authentication​

HMAC signature (required)​

Webhook Headers & Metadata​

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

Authentication

HMAC signature (required)

Webhook Headers & Metadata

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`)