.png)
Envoy Integration Guide
Connect Envoy workplace, visitor, employee, location, and delivery data with enterprise applications through REST APIs, OAuth, selected webhook events, and Martini workflows.
Envoy integration options at a glance
Envoy provides developer-facing REST APIs for workplace and visitor-management data, with OAuth-based application authorization and tenant-specific permissions. Selected workplace events can be delivered through webhook-style notifications, although coverage must be confirmed for the required product, object, and lifecycle event. Martini can consume Envoy REST endpoints, handle pagination and checkpoints, transform JSON payloads, and synchronize Employees, Visitors, Invites, Locations, Deliveries, and Hosts with downstream systems. Martini can also expose an API endpoint for Envoy callbacks, validate incoming requests, apply business rules, and route event results to operational applications. General bulk APIs, direct database access, GraphQL, SOAP, and file interfaces were not confirmed.
| Integration point | Supported by Envoy? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Access and manage supported Envoy workplace, visitor-management, employee, location, invitation, host, and delivery resources. Confirm the applicable product, API version, scopes, and write operations. | Martini can consume Envoy REST endpoints from workflows, process JSON responses, handle pagination, map fields, apply business rules, and expose normalized APIs for downstream systems. |
| Webhooks / outbound callbacks | Limited | Receive selected visitor arrival, sign-in, sign-out, delivery, or other product-specific workplace event notifications. Coverage is not confirmed for every object or state transition. | Martini can expose an API endpoint, validate and authenticate the callback according to Envoy requirements, deduplicate events, transform payloads, and route them to enterprise applications. |
| Authentication | Yes | OAuth-based application authorization provides access to Envoy resources subject to tenant authorization, scopes, and organization permissions. | Martini can manage OAuth configuration and access secrets through secure environment configuration, invoke authenticated APIs, and separate development, testing, and production settings. |
| Scheduled synchronization | Yes | Retrieve Employees, Hosts, Locations, Visitors, Invites, or Deliveries on a schedule when event coverage is incomplete or a periodic reconciliation is required. | Martini can trigger workflows on a schedule, follow pagination, persist checkpoints, upsert target records, and retry transient failures. |
| Pagination and incremental retrieval | Yes | Support larger collection synchronizations without assuming a general-purpose bulk API. Use documented pagination and incremental filters where available. | Martini workflows can iterate through pages, persist cursors or last-successful-sync values, stop at the end of a collection, and resume after partial failures. |
| Bulk / asynchronous APIs | Not confirmed | A general-purpose bulk or asynchronous Envoy API was not confirmed. Large transfers should use pagination, filtering, throttling, and checkpointing instead. | Martini can orchestrate controlled page-based processing and scheduled batches without assuming a bulk endpoint. |
| GraphQL APIs | Not confirmed | No official Envoy GraphQL API was confirmed for this research; REST should be treated as the default API style. | Martini supports GraphQL consumption generally, but an Envoy GraphQL integration should not be designed without confirmed Envoy documentation. |
| SOAP APIs | Not confirmed | No official Envoy SOAP API was confirmed, so SOAP is not recommended for a new Envoy integration. | Martini supports SOAP consumption generally, but there is no confirmed Envoy SOAP endpoint to consume. |
| File, database, and analytics access | Not confirmed | No general Envoy file-import, file-export, attachment, direct database, or analytics interface was confirmed. | Martini should use Envoy APIs and supported event mechanisms rather than assuming direct data access or file exchange. |
How Envoy exposes data and business events
Envoy REST APIs
Envoy’s primary integration mechanism is its developer-facing REST API for supported workplace and visitor-management resources. The available products, fields, lifecycle operations, scopes, and pagination behavior depend on the selected Envoy API and tenant configuration.
Martini implementation pattern
Martini implementation pattern: Martini workflows authenticate with OAuth, call the applicable Envoy endpoints, follow pagination, map JSON resources into canonical models, apply business rules, and write results to enterprise applications or a data store. A Martini API can also expose a controlled façade over selected Envoy operations.
Implementation sequence
Envoy Webhook Events
Envoy supports webhook-style event delivery for selected workplace events, including potentially visitor arrival, sign-in, sign-out, and delivery-related notifications. Coverage must be confirmed for the specific Envoy product, tenant, and required event.
Martini implementation pattern
Martini implementation pattern: Martini exposes an authenticated API endpoint for the callback, validates the request using the mechanism documented by Envoy, records an idempotency key, and routes the event through a workflow. When the notification lacks sufficient detail, the workflow retrieves the current Envoy resource before notifying or updating downstream systems.
Implementation sequence
Envoy OAuth Authorization
Envoy documents OAuth-based application authorization for applications connecting to its developer platform. Scopes, tenant permissions, token behavior, and available resources depend on the API product and organization configuration.
Martini implementation pattern
Martini implementation pattern: Martini stores client credentials and tokens in secure environment configuration, uses the configured authorization flow to call Envoy, and keeps environment-specific settings separate for development, testing, and production. Resource access is limited to the scopes and tenant permissions granted by Envoy.
Implementation sequence
Scheduled Envoy Synchronization
Scheduled retrieval is appropriate for Employees, Hosts, Locations, Visitors, Invites, or Deliveries when event coverage is incomplete or periodic reconciliation is required. A general-purpose Envoy bulk API was not confirmed.
Martini implementation pattern
Martini implementation pattern: A scheduler starts a workflow that retrieves Envoy collections page by page, applies incremental filters where supported, maps and upserts objects, and stores a durable checkpoint. The workflow uses bounded retries and can resume after a partial failure without blindly inserting duplicate data.
Implementation sequence
Common Envoy integration patterns
Pattern 1: Route visitor events to workplace notifications
When to use this pattern
Use this pattern when workplace, security, or host teams need near-real-time notifications for selected Envoy visitor events such as arrival, sign-in, or sign-out. Event availability must be confirmed for the relevant Envoy product and tenant.
Integration direction
Example Mapping
| Envoy Field | Canonical Field | Target Field |
|---|---|---|
| visitor.name | person.displayName | message.visitorName |
| host.name | visit.hostName | message.hostName |
| location.name | workplace.locationName | message.location |
| visit.status | visit.status | message.eventStatus |
Martini implementation pattern
Martini receives the Envoy callback through an exposed API, validates it, derives an event or resource-based idempotency key, and retrieves the current Visitor when necessary. A workflow applies office, visitor-type, and status rules before formatting and sending the notification. Duplicate events are suppressed, while transient downstream failures are retried and permanent failures are routed to operational handling.
Martini capabilities used
- APIs
- workflows
- webhook consumption
- data mapping
- business rules
- error handling
Pattern 2: Synchronize Envoy employees and locations
When to use this pattern
Use this pattern when an enterprise needs Envoy workplace context aligned with Workday, Okta, Google Workspace, or another employee and organization application. It is also useful as a periodic reconciliation when webhook coverage is incomplete.
Integration direction
Example Mapping
| Envoy Field | Canonical Field | Target Field |
|---|---|---|
| Employees.id | employee.externalId | worker.envoyId |
| Employees.name | employee.displayName | user.displayName |
| Employees.locationId | employee.locationId | user.workplaceLocationId |
| Locations.name | workplace.name | location.displayName |
Martini implementation pattern
A scheduled Martini workflow calls the applicable Envoy REST endpoints, follows pagination, and maps Employees and Locations into the target model. It uses external-ID upserts, handles deactivated or removed objects according to retention rules, stores a checkpoint after successful pages, and retries throttling or transient server errors with bounded backoff.
Martini capabilities used
- scheduled workflows
- API consumption
- pagination orchestration
- data mapping
- checkpointing
- retry handling
Pattern 3: Create operational work for visitor exceptions
When to use this pattern
Use this pattern when selected visitor lifecycle events should create or update a ServiceNow or Jira task, incident, or work item—for example, a visitor arrives without a matching host or invitation.
Integration direction
Example Mapping
| Envoy Field | Canonical Field | Target Field |
|---|---|---|
| Visitors.id | visitor.externalId | workItem.envoyVisitorId |
| Visitors.status | visit.status | workItem.visitorStatus |
| Hosts.name | visit.hostName | workItem.host |
| Locations.name | workplace.locationName | workItem.location |
Martini implementation pattern
Martini receives a supported Envoy event or detects the condition during synchronization, validates required fields, and applies exception rules by location and status. It creates or updates the target work item with a stable correlation key, records the Envoy identifiers, and prevents duplicate tasks while sending failed records to an operational error path.
Martini capabilities used
- event-driven workflows
- API orchestration
- field mapping
- conditional routing
- idempotency
- error handling
Pattern 4: Publish delivery data for operational reporting
When to use this pattern
Use this pattern when workplace operations need Delivery information in a reporting API, database, Slack channel, or Microsoft Teams workflow. It is suitable for scheduled retrieval when delivery event coverage is limited.
Integration direction
Example Mapping
| Envoy Field | Canonical Field | Target Field |
|---|---|---|
| Deliveries.id | delivery.externalId | delivery.envoyId |
| Deliveries.receivedAt | delivery.receivedTimestamp | delivery.receivedAt |
| Deliveries.locationId | workplace.locationId | delivery.locationId |
| Deliveries.status | delivery.status | delivery.currentStatus |
Martini implementation pattern
A Martini scheduler retrieves supported Delivery data page by page, normalizes timestamps and location identifiers, filters fields according to privacy and retention requirements, and writes the result to the selected target. The workflow applies deduplication and retention rules, records checkpoints, and retries throttled or transient API calls.
Martini capabilities used
- scheduler triggers
- REST API consumption
- JSON transformation
- data mapping
- privacy rules
- monitoring and retries
Applications commonly integrated with Envoy
Envoy workplace data can be connected to collaboration, service management, identity, CRM, productivity, and employee systems. The exact event coverage, write operations, and provisioning behavior should be confirmed for the relevant Envoy product, API version, and tenant.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Slack | Notify hosts, security teams, or workplace operations when visitors arrive or deliveries are received. | Envoy → Martini → Slack | Martini exposes an API for selected Envoy webhook events, validates and deduplicates the notification, maps the visitor, host, location, or delivery details, applies office-specific routing rules, and calls Slack to publish the appropriate message. |
| Microsoft Teams | Deliver workplace and visitor notifications to teams using Microsoft 365 collaboration channels. | Envoy → Martini → Microsoft Teams | A Martini workflow receives or retrieves Envoy event data, normalizes timestamps and location details, applies notification rules, and invokes the Microsoft Teams interface used by the organization, with retries for transient delivery failures. |
| Salesforce | Associate visits, hosts, or visitor-related activity with Accounts, Contacts, and customer-facing operations. | Envoy → Martini → Salesforce | Martini retrieves or receives Envoy visitor information, resolves external IDs against Salesforce Accounts or Contacts, maps visit status and host details, and upserts activity while routing ambiguous matches to an exception workflow. |
| ServiceNow | Create workplace, security, facilities, or visitor-related tasks and incidents. | Envoy → Martini → ServiceNow | Martini processes selected Envoy visitor or delivery events, evaluates rules such as an arrival without a matching host or invitation, and creates or updates ServiceNow work items with idempotency and retry controls. |
| Okta | Align employee identity and lifecycle information with workplace access and employee data. | Okta → Martini → Envoy | A scheduled Martini workflow retrieves authorized Okta employee changes, maps identity and location attributes to the Envoy employee model where supported, and records unsupported operations or permission failures for review. |
| Google Workspace | Synchronize employee or calendar-related workplace information for organizations using Google productivity services. | Google Workspace → Martini → Envoy | Martini coordinates the applicable Google Workspace and Envoy APIs, applies field and time-zone mappings, and writes only the Envoy resources and operations confirmed for the tenant. |
| Jira | Create operational work items for facilities, security, or workplace exceptions. | Envoy → Martini → Jira | Martini transforms Envoy events into Jira issue fields, assigns projects and issue types using location or event rules, prevents duplicate issues with a stable key, and retries transient API failures. |
| Workday | Use employee and organizational data to support workplace onboarding and employee synchronization. | Workday → Martini → Envoy | A scheduled Martini workflow retrieves approved Workday changes, maps employee and organizational identifiers to Envoy fields where supported, applies create or update rules, and checkpoints successful pages for safe restart. |
How to build a Envoy integration in Martini
Objective
Establish a controlled connection to Envoy using the authorization method and permissions required by the selected API product.
Instructions in Martini
- Confirm the Envoy product, API version, tenant, resources, and required OAuth scopes
- Store client credentials, tokens, and environment-specific settings in protected Martini configuration
- Separate development, testing, and production Envoy organizations and credentials
Objective
Select an event-driven or scheduled trigger based on the required Envoy event coverage and synchronization latency.
Instructions in Martini
- Use a Martini API endpoint for supported Envoy webhook-style events
- Use a scheduler when periodic reconciliation or unsupported event coverage is required
- Confirm the callback authentication or signature mechanism before accepting events
Objective
Receive event payloads or retrieve current Envoy resources with pagination and incremental controls.
Instructions in Martini
- Call the applicable Envoy REST endpoint from a workflow
- Follow documented pagination and use safe page sizes
- Retrieve the current Visitor, Delivery, Employee, Host, Invite, or Location when an event lacks sufficient detail
- Persist a cursor, timestamp, or checkpoint where supported
Objective
Coordinate validation, enrichment, business rules, target calls, and operational outcomes in a maintainable Martini workflow.
Instructions in Martini
- Validate required identifiers, statuses, timestamps, and tenant context
- Correlate Visitors with Hosts, Invites, and Locations where needed
- Apply office, visitor-type, privacy, retention, and exception rules
- Route valid, duplicate, and failed messages through separate paths
Objective
Convert Envoy JSON structures into canonical models and target-specific request formats.
Instructions in Martini
- Create explicit mappings for Envoy object and status fields
- Normalize time zones while retaining the source location and original offset
- Use stable external identifiers and preserve correlation data
- Keep vendor-specific payload structures separate from downstream models
Objective
Update enterprise applications, databases, reporting APIs, or collaboration systems with controlled idempotent operations.
Instructions in Martini
- Upsert Employees, Locations, Visitors, Invites, Deliveries, or Hosts where supported
- Create or update ServiceNow, Jira, Slack, Microsoft Teams, Salesforce, or other approved targets
- Apply target validation and avoid copying unnecessary personal information
- Record source and target identifiers for reconciliation
Common Envoy data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Locations | Represent offices or workplace locations managed in Envoy and provide location context for visitors, employees, and deliveries. | ServiceNow, Salesforce, Workday, Google Workspace, reporting databases | Martini retrieves Locations through REST APIs, normalizes identifiers and time zones, and upserts them using external-ID mappings and checkpointed synchronization. |
| Employees | Represent employees associated with an Envoy organization or workplace location. | Workday, Okta, Google Workspace, Salesforce | Martini maps employee identity and location attributes, applies lifecycle and privacy rules, and handles pagination, deactivation, and unmatched records. |
| Visitors | Represent people visiting a workplace, including registration and visit status. | ServiceNow, Slack, Microsoft Teams, Salesforce, Jira | Martini can process visitor API responses or selected webhook events, normalize statuses and timestamps, enforce notification rules, and use stable identifiers for idempotency. |
| Invites | Represent invitations created for expected visitors and support comparison between expected and actual visits. | ServiceNow, Salesforce, Slack, Microsoft Teams | Martini synchronizes supported Invite fields, correlates invitations with Visitors and Hosts, and confirms create or update capabilities before sending data back to Envoy. |
| Deliveries | Represent packages or deliveries received at a workplace. | Slack, Microsoft Teams, ServiceNow, reporting databases | Martini retrieves supported Delivery data or processes delivery notifications, applies retention and routing rules, and writes normalized operational data to target systems. |
| Hosts | Represent employees or workplace contacts associated with visitors and visits. | Slack, Microsoft Teams, Salesforce, ServiceNow | Martini resolves Host identifiers and contact details, enriches visitor notifications, and handles missing or changed host relationships through business rules. |
Authentication and security considerations
OAuth and tenant authorization
Envoy documents OAuth-based application authorization. Required scopes, resource permissions, token behavior, and organization access depend on the selected Envoy API product and tenant.
Credential protection
Store Envoy client credentials, tokens, and environment-specific configuration in protected Martini secrets and configuration. Separate development, testing, and production organizations and rotate credentials under operational policy.
Webhook protection
Validate the authentication or signature mechanism documented for the relevant Envoy webhook product before processing callbacks. Restrict the Martini API endpoint and do not trust a request solely because it reaches a private URL.
Privacy
Visitor and employee data may contain personal information. Minimize copied fields, restrict API access, avoid unnecessary sensitive values in logs, and apply retention and deletion rules in downstream systems.
Operational considerations for Envoy integrations
Pagination and checkpoints
Collection endpoints may be paginated. Follow Envoy’s documented mechanism, persist cursors or last-successful-sync values where available, and design workflows to resume after partial failures.
Rate limits and retries
Use bounded retries with exponential backoff for throttling and transient failures, respect server-provided retry timing, and route repeatedly failing records to an operational exception process.
Idempotency and ordering
Webhook notifications may be duplicated or arrive out of order. Use a stable event or resource-based key, tolerate delayed updates, and retrieve the current Envoy object when the event payload is insufficient.
Schema and time zones
Confirm API versions, object fields, status values, and enum changes. Normalize timestamps while retaining the source location and original offset for workplace activity.
Testing and monitoring
Test representative visitor, employee, location, invitation, host, and delivery scenarios across non-production environments. Monitor API consumption, workflow failures, token issues, pagination behavior, and downstream write results.
Why use Martini instead of scripts or point-to-point integrations?
Orchestrate more than API calls
Martini coordinates Envoy API consumption, webhook reception, scheduling, enrichment, conditional routing, target writes, and operational exception handling in reusable workflows.
Keep mappings maintainable
Explicit mappings and canonical models isolate Envoy payload structures from downstream applications. This makes status, time-zone, privacy, and schema-change rules easier to test and maintain.
Support multiple delivery patterns
One Martini implementation can combine real-time callbacks for selected events with scheduled REST synchronization for reconciliation and resources without suitable event coverage.
Improve operational control
Centralized authentication configuration, checkpoints, idempotency, bounded retries, logging, and monitoring provide more control than isolated scripts or point-to-point integrations.
Frequently asked questions
Envoy can be integrated through its developer-facing REST APIs, OAuth-based application authorization, selected webhook-style event notifications, and scheduled retrieval of supported workplace resources. REST should be treated as the primary mechanism, while event coverage and write operations must be confirmed for the relevant Envoy product, API version, and tenant.
Yes. Martini can consume Envoy REST APIs, handle OAuth configuration, process JSON resources, run scheduled synchronization workflows, and receive selected Envoy webhook events through an exposed API. A native Martini Envoy connector is not documented in the supplied product context.
No. A dedicated Envoy connector is not required. Martini can integrate using Envoy’s confirmed native REST APIs, OAuth authorization, and supported webhook-style callbacks, with workflows handling mapping, business rules, synchronization, and error processing.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Envoy with Martini. Integrations are subject to the provisioned capacity of the Martini environment. Separate costs may apply from Envoy, infrastructure, or other third-party systems based on subscription, usage, and deployment model.
Use Envoy REST APIs as the default mechanism and evaluate OAuth scopes and tenant permissions before implementation. Use webhook-style notifications for selected events when the required coverage is confirmed, and use scheduled, paginated synchronization for reconciliation or resources without suitable event coverage. GraphQL, SOAP, general bulk APIs, file interfaces, and direct database access were not confirmed.
Martini can expose an API endpoint for supported Envoy webhook-style notifications. Envoy event coverage is selective, so arrival, sign-in, sign-out, delivery, or other required events must be confirmed for the specific Envoy product and tenant. Martini can validate, deduplicate, enrich, and route those events.
A Martini workflow can call Envoy REST endpoints on a schedule, follow pagination, apply incremental filters where available, map objects, and upsert them into a target system. Durable checkpoints, external-ID mappings, bounded retries, and reconciliation rules help prevent missed or duplicated changes.
Martini can map Envoy JSON into canonical and target-specific models, apply validation and business rules, and classify authentication, authorization, throttling, validation, not-found, and transient server failures. Workflows can use bounded exponential backoff, server-provided retry timing, idempotency keys, checkpoints, monitoring, and exception handling.
Related Martini documentation
Workflows
Data Mapping
Connect Envoy with Martini
Use Martini to connect Envoy workplace data and selected events with enterprise applications through secure APIs, reusable workflows, scheduled synchronization, and controlled transformations.