Study guide
8.3 Webex Developer Platform & APIs
Cisco 350-801 CLCOR CCNP/CCIE Collaboration Core v2.0
Track your progress as you read
Finished sections get a check mark.
1 Chapter 1: Collaboration Architecture, Deployment Models, Sizing & Upgrades
1.1 Collaboration Architecture & Deployment Models 1.2 Capacity Planning, Sizing & Bandwidth Considerations 1.3 High Availability, Redundancy & Disaster Recovery 1.4 Cisco Unified CM Cluster Upgrade Process
2 Chapter 2: Edge Architecture, Security & Network Services
2.1 Collaboration Edge Architecture: CUBE & Expressway 2.2 Security Protocols & PKI: SSO, OAuth, TLS & SRTP 2.3 Network Infrastructure Services: DNS, NTP, DHCP & LDAP
3 Chapter 3: Protocols, Codecs & Endpoint Provisioning
3.1 SIP Signaling Architecture & Call Flows 3.2 Session Description Protocol (SDP) & Early Offer vs. Delayed Offer 3.3 Audio/Video Codecs & DTMF Relay 3.4 Endpoint Deployment, Onboarding & Troubleshooting
4 Chapter 4: CUCM Dial Plan Fundamentals & Digit Analysis
4.1 Partitions and Calling Search Spaces (CSS) 4.2 Route Patterns, Route Groups & Route Lists 4.3 Translation Patterns, Transformation Patterns & Digit Manipulation 4.4 Globalized Call Routing & Local Route Group (LRG)
5 Chapter 5: Advanced Call Control, Call Routing & User Management
5.1 Call Admission Control (CAC), Locations & AAR 5.2 Toll Fraud Prevention & Call Privileges 5.3 CUCM User Management, LDAP Integration & RBAC 5.4 Administrative XML (AXL) API & Dial-Plan Troubleshooting Tools
6 Chapter 6: Cisco Unity Connection & Voicemail Integration
6.1 Cisco Unity Connection Architecture & SIP Integration 6.2 Mailbox Provisioning, User Templates & Class of Service 6.3 Message Waiting Indication (MWI) & Troubleshooting 6.4 Call Handlers & Directory Handlers
7 Chapter 7: IOS XE Voice Gateways, CUBE & Media Resources
7.1 Cisco IOS XE Voice Gateways & Dial Peers 7.2 Voice Translation Rules and Translation Profiles 7.3 Cisco Unified Border Element (CUBE) Configuration & Redundancy 7.4 IOS XE Media Resources & DSP Management
8 Chapter 8: Webex Architecture, Control Hub, Meetings & Messaging
8.1 Webex Suite Overview & Control Hub Architecture 8.2 Cloud Identity Management, SCIM & Directory Connector 8.3 Webex Developer Platform & APIs 8.4 Configuring Webex Cloud Meetings 8.5 Configuring Webex Cloud Messaging
9 Chapter 9: Webex Calling Routing, Permissions & PSTN Connectivity
9.1 Webex Calling Architecture, Locations & Number Management 9.2 Webex Calling Routing, Trunks & Dial Plans 9.3 Webex Calling Call Routing Process & Translation Patterns 9.4 Webex Calling Toll Fraud Prevention, Call Permissions & Operating Modes 9.5 PSTN Connectivity: Cloud-Connected PSTN (CC-PSTN) & Cisco Calling Plans 9.6 Webex Calling Local Gateway (LGW) Architecture & Configuration
10 Chapter 10: Webex Hybrid Services & Cloud Connected UC
10.1 Cloud-Connected UC (CCUC) Architecture & Telemetry 10.2 Webex Hybrid Calendar & Hybrid Directory Services 10.3 Webex Video Mesh & Hybrid Data Security
11 Chapter 11: Media Quality, QoS Engineering & Troubleshooting
11.1 Real-Time Media Characteristics & Impairments 11.2 QoS Classification, Marking & Trust Boundaries 11.3 Low Latency Queuing (LLQ) Configuration on Cisco IOS XE 11.4 Troubleshooting Media Quality & Call Failures
8.3 Webex Developer Platform & APIs
Key Takeaways Explain This Topic AI
The Webex REST API platform operates over base URL https://webexapis.com/v1 using standard HTTP verbs and JSON payloads, enforcing rate limits via HTTP 429 Too Many Requests responses containing a mandatory Retry-After header.
Webex authentication provides four distinct mechanisms: Personal Access Tokens (12-hour developer testing), Bot Accounts (permanent bot tokens triggered via @mentions), OAuth 2.0 Integrations (3-legged authorization code flow), and Service Apps (machine accounts that a Full Admin authorizes in Control Hub and that then use access and refresh tokens).
OAuth 2.0 integrations grant short-lived access tokens valid for 14 days and refresh tokens valid for 90 days, enabling secure third-party delegated authorization without storing user credentials.
Webhooks deliver real-time, asynchronous HTTP POST notifications to external HTTPS target URLs upon resource events (created, updated, deleted), eliminating inefficient polling architectures.
Webhook security is maintained by computing the HMAC-SHA1 cryptographic signature of the raw request payload using a shared secret and verifying it against the incoming X-Spark-Signature HTTP header.
Last updated: October 2026
8.3 Webex Developer Platform & APIs
Enterprise collaboration environments demand extensive integration with business applications, workflow automation tools, and administrative management platforms. The Cisco Webex Developer Platform provides programmable RESTful APIs, event-driven webhooks, and secure authentication models that allow engineers to automate user provisioning, control calling features, and build intelligent collaboration bots.
1. Webex Developer Platform Architecture & REST Standards
The Webex Developer Platform exposes a microservices-backed REST API architecture. All platform operations follow established Representational State Transfer (REST) conventions:
Base Endpoint URL : https://webexapis.com/v1/{resource}
Transport Security : Enforced strictly over Transport Layer Security (TLS 1.2 or 1.3) via HTTPS on TCP port 443.
Data Interchange Format : Request payloads and response structures utilize standard JSON formatted with UTF-8 encoding ( Content-Type: application/json; charset=utf-8 ).
Standard HTTP Methods :
GET : Retrieve a resource representation or paginated resource collections.
POST : Create a new resource or execute a functional command.
PUT : Complete update or replacement of an existing resource object.
PATCH : Partial modification of specific resource attributes.
DELETE : Permanently remove a resource.
HTTP Response Status Codes
HTTP Status Code Meaning Architectural Context
200 OK Success Request succeeded; returns requested JSON data or synchronous update confirmation.
201 Created Created New resource (user, space, webhook) provisioned successfully; returns created object and URI.
204 No Content No Content Request succeeded, but response body is intentionally empty (standard for DELETE operations).
400 Bad Request Malformed Request Syntax error, invalid query parameter, or malformed JSON payload.
401 Unauthorized Authentication Failure Missing, expired, or invalid HTTP Bearer authentication token.
403 Forbidden Authorization Failure Authenticated identity lacks administrative permissions or required OAuth scopes.
404 Not Found Resource Missing Specified resource UUID does not exist or has been deleted.
429 Too Many Requests Rate Limit Exceeded API rate ceiling breached; client must pause and retry after the duration specified in Retry-After .
API Rate Limiting Mechanics
To safeguard cloud infrastructure against denial-of-service degradation, Webex enforces dynamic rate limiting using a token-bucket algorithm:
HTTP 429 Response : When an application exceeds its allotted request volume, the Webex API server rejects subsequent calls with HTTP status 429 Too Many Requests .
Retry-After Header : The response includes a mandatory HTTP header: Retry-After: <seconds> (e.g. Retry-After: 45 ), denoting the exact duration the application must pause before transmitting further requests.
Exponential Backoff : Robust applications must parse the Retry-After header, queue pending requests, and implement exponential backoff with randomized jitter to prevent burst retries.
2. Core API Resource Endpoints +-------------------------------------------------------------------------------------+
- | WEBEX REST API ENGINE |
- | (https://webexapis.com/v1) |
- +-------------------------------------------------------------------------------------+
- | | | |
- v v v v
- /v1/people /v1/rooms /v1/messages /v1/telephony
- +------------------+ +------------------+ +------------------+ +------------------+
- | User Lifecycle | | Spaces & Groups | | Rich Messaging | | Webex Calling |
- | - Provision User | | - Create Spaces | | - Text / Markdown| | - Call Queues |
- | - Assign License | | - Add Members | | - File Uploads | | - Hunt Groups |
- | - Caller ID Info | | - Moderation | | - Adaptive Cards | | - Auto Attendant |
- +------------------+ +------------------+ +------------------+ +------------------+
- 1. /people (User Management)
Manages the enterprise identity lifecycle, profile fields, and service licenses:
GET /v1/people : Retrieves a paginated list of users; supports filtering by email , displayName , or orgId .
POST /v1/people : Provisions a new user, allocating service licenses (e.g., Calling Professional, Meetings) and assigning calling extensions.
GET /v1/people/{personId} : Retrieves granular profile information for a specific user UUID.
GET /v1/people/me : Returns identity details and scopes for the currently authenticated bearer token.
2. /rooms (Spaces Management)
Administers collaborative workspaces (historically referred to as spaces or rooms):
GET /v1/rooms : Lists spaces where the authenticated caller is an active participant.
POST /v1/rooms : Creates a new direct or group collaboration space with a specified title .
PUT /v1/rooms/{roomId} : Updates space metadata, renames spaces, or modifies team associations.
/memberships : Complementary resource managing participant membership within spaces ( GET , POST , DELETE ).
3. /messages (Messaging & Interactive Cards)
Governs content transmission, document distribution, and workflow interactions:
POST /v1/messages : Dispatches a message to a space ( roomId ) or direct recipient ( toPersonEmail / toPersonId ).
Payload Parameters :
text : Plain-text representation displayed on notifications and legacy clients.
markdown : Formatted text supporting bolding, code blocks, lists, and hyperlinks.
files : Array of public HTTPS URLs containing files to attach to the space.
attachments : JSON payload embedding an Adaptive Card containing interactive input forms, buttons, and dropdown menus.
/attachmentActions : Captures user button clicks and form submissions submitted through Adaptive Cards.
4. /telephony & /telephony/config (Webex Calling Provisioning)
Provides programmatic administration of enterprise call routing infrastructure:
Automates provisioning of Webex Calling Locations, internal dial plans, and emergency routing numbers.
Configures auto-attendants, hunt groups, call queues, call pickup groups, and shared call appearances.
Manages individual user calling features: call forwarding rules, do-not-disturb, simultaneous ring, and unified voicemail settings.
3. Webex Authentication & Authorization Methods
Security is paramount when accessing collaboration APIs. Webex provides four distinct authentication and authorization models tailored to specific operational contexts.
Architectural Comparison of Authentication Models
Authentication Method Token Validity Refresh Support Scopes & Permissions Primary Use Case
Personal Access Token 12 Hours No (Cannot refresh) Full privileges of developer account CLI testing, Postman, rapid prototyping
Bot Account Permanent (Indefinite) No (Static token) Scoped bot permissions Automated notifications, interactive chat
OAuth 2.0 Integration 14 Days Yes (90-day rolling refresh) Granular user-delegated scopes Third-party multi-tenant apps acting on user behalf
Service App 14-day access token Yes (90-day refresh token) Admin-approved organization scopes Server-to-server backend integrations
1. Personal Access Tokens (PAT)
Obtained directly from the Webex Developer Portal ( developer.webex.com ) when logged in with developer credentials.
Valid strictly for 12 hours from issuance.
Operational Boundary : Because PATs expire quickly and cannot be refreshed, they must never be hard-coded into production scripts, daemon processes, or scheduled cron tasks.
2. Bot Accounts
Programmatic identities created on developer.webex.com that represent automated services or chatbots.
Each bot receives a unique identity: <botname>@webex.bot , a distinct avatar, and a permanent API access token.
Privacy & @Mention Rule : In 1:1 direct spaces, the bot automatically receives all messages. In multi-user group spaces, the bot receives message events only when explicitly @mentioned by a user. This architectural safeguard guarantees that bots cannot eavesdrop on private human conversations in group spaces.
3. OAuth 2.0 Integrations (3-Legged Authorization Code Flow)
Used when a third-party application needs to perform actions on behalf of a human user without learning or storing the user's password:
User Authorization Request : The application redirects the user's browser to the Webex authorization URL: GET https://webexapis.com/v1/authorize?client_id=C123...&response_type=code&redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth&scope=spark%3Amessages_write%20spark%3Apeople_read&state=xyz123
Consent & Code Issuance : The user authenticates at Webex and consents to the requested scopes (e.g. spark:messages_write , spark:people_read ). Webex redirects the user back to the application's redirect_uri with a temporary authorization code: GET https://app.example.com/oauth?code=AUTH_CODE_456&state=xyz123
Code Exchange for Access & Refresh Tokens : The application server makes a backend POST request to exchange the code: POST https://webexapis.com/v1/access_token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&client_id=C123...&client_secret=SEC789...&code=AUTH_CODE_456&redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth
Token Lifecycles :
Access Token : Valid for 14 days (1,209,600 seconds); passed in Authorization: Bearer <access_token> headers.
Refresh Token : Valid for 90 days (7,776,000 seconds).
Token Refresh : Before the 14-day access token lapses, the app sends grant_type=refresh_token to receive a fresh access token and a renewed 90-day refresh token, ensuring uninterrupted access without user re-authentication.
4. Service Apps (Machine-to-Machine Integration)
Designed for enterprise backend systems (such as HR onboarding engines or archiving services) that require organization-wide access without human interaction.
How it works:
The developer registers the Service App on developer.webex.com, selects its scopes, and receives a client ID and client secret.
A Full Administrator of the customer organization authorizes the app in Control Hub. Apps that request compliance scopes need a Full Admin who also holds the Compliance Officer role.
The developer retrieves the organization's access token (about 14 days) and refresh token (about 90 days) from the app's Org Authorizations page or through the Applications API, using the client ID, client secret, and target organization ID, and refreshes it like an integration token.
If the administrator later revokes the authorization in Control Hub, both tokens stop working.
4. Webhooks Architecture & Event-Driven Automation
Polling API endpoints (such as repeatedly calling GET /v1/messages every few seconds) is inefficient, consumes network bandwidth, and rapidly exhausts API rate limits (HTTP 429). Webex Webhooks provide an asynchronous, event-driven push architecture.
- Webhook Registration
- Applications register webhooks via POST https://webexapis.com/v1/webhooks : {
- "name": "Support Space Alert Hook",
- "targetUrl": "https://api.enterprise.com/webhooks/webex",
- "resource": "messages",
- "event": "created",
- "filter": "roomId=Y2lzY29zcGFyazovL3VzL1JPT00vMGI5...",
- "secret": "SuperSecretSharedKey987!"
- }
targetUrl : Must be reachable from the internet; use HTTPS with a publicly trusted certificate so that the notifications are protected in transit.
resource : The entity type to monitor ( messages , memberships , rooms , telephony_calls , attachmentActions ).
event : The trigger event ( created , updated , deleted , all ).
secret : A shared secret string used to cryptographically verify payload integrity and authenticity.
- Webhook Event Delivery Payload & Content Decoupling
- When an event occurs, Webex dispatches an HTTP POST request to the configured targetUrl : {
- "id": "Y2lzY29zcGFyazovL3VzL1dFQkhPT0svZjQ...",
- "name": "Support Space Alert Hook",
- "targetUrl": "https://api.enterprise.com/webhooks/webex",
- "resource": "messages",
- "event": "created",
- "orgId": "Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8x...",
- "actorId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9hMT...",
- "data": {
- "id": "Y2lzY29zcGFyazovL3VzL01FU1NBR0UvYjI...",
- "roomId": "Y2lzY29zcGFyazovL3VzL1JPT00vMGI5...",
- "roomType": "group",
- "personId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9hMT...",
- "personEmail": "engineer@example.com",
- "created": "2026-10-06T15:30:00.000Z"
- }
- }
Architectural Privacy Note : Notice that the webhook notification payload deliberately does not contain the message text or file contents. This prevents unauthorized exposure of message contents if webhook URLs are misconfigured. To read the message text, the application must take the data.id and issue an authenticated call ( GET /v1/messages/{data.id} ) using its authorized bot or user token.
Webhook Cryptographic Verification ( X-Spark-Signature )
To prevent spoofing, tampering, and replay attacks, Webex signs every webhook payload:
Webex computes a Hash-based Message Authentication Code using SHA-1 ( HMAC-SHA1 ) over the raw HTTP request body bytes, using the shared secret defined during webhook registration:
Signature = HMAC-SHA1 ( secret , raw_body_bytes ) \text{Signature} = \text{HMAC-SHA1}(\text{secret}, \text{raw\_body\_bytes}) Signature = HMAC-SHA1 ( secret , raw_body_bytes )
Webex includes the resulting hexadecimal signature string in the incoming HTTP request header: X-Spark-Signature: 3b7f2a9c0e41d5b8a6f39c27e1d0b4a85c6e9f12
Upon receiving the POST notification, the application server computes the identical HMAC-SHA1 digest on the raw unparsed request body using its stored shared secret.
The application executes a constant-time string comparison between its calculated digest and the X-Spark-Signature header value. If they match, the payload is authentic; if they differ, the server rejects the request with HTTP 401 or 403.