Plain

Loading version...

Port's Plain integration allows you to model Plain support resources in your software catalog and ingest data into them.

Supported resources CompanyTenantUserMachine userCustomerThreadThread messageDiscussionDiscussion message

Prerequisites

• A Plain workspace with permission to create a machine-user API key.
• Your Port user role is set to Admin.
• A Plain API key created on a machine user (Settings → Machine Users → Add API key). The token looks like plainApiKey_….
  • Grant at least company:read, tenant:read, user:read, customer:read, thread:read, and timeline:read.
  • Additional permissions may be needed depending on which kinds and nested fields you sync (for example roles:read, tier:read, machineUser:read, customerTenantMembership:read, and webhook target permissions for live events).

Setup

Choose one of the following installation methods. Not sure which method is right for your use case? Check the available installation methods.

Configuration

Port integrations use a YAML mapping block to ingest data from the third-party api into Port.

The mapping makes use of the JQ JSON processor to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API.

Selectors

Every kind supports pageSize (default 100, max 100) to control GraphQL list page size for that mapping block.

Additional selector flags:

• excludeDeleted (machine-user only) - When true, skip deleted machine users during resync. When false (default), sync all machine users including deleted ones. You can filter in Port with a query such as .isDeleted == false.
• excludeDoneThreads (thread, thread-message, discussion, discussion-message) - When true, sync only TODO and SNOOZED threads.
• threadStatuses (thread, thread-message, discussion, discussion-message) - Optional list of thread statuses to sync (for example [TODO, SNOOZED]). Ignored when excludeDoneThreads is true. Omit it to sync every status.
• excludeAiDiscussions (discussion, discussion-message) - When true, skip Cursor and agent-session discussions (and their messages) at fetch time.

Default mapping configuration

This is the default mapping configuration you get after installing the Plain integration.

Default mapping configuration (click to expand)

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: company
    selector:
      query: "true"
      pageSize: 100
    port:
      entity:
        mappings:
          identifier: .id
          title: .name
          blueprint: '"plainCompany"'
          properties:
            domainName: .domainName
            createdAt: .createdAt.iso8601
            updatedAt: .updatedAt.iso8601
  - kind: tenant
    selector:
      query: "true"
      pageSize: 100
    port:
      entity:
        mappings:
          identifier: .id
          title: .name
          blueprint: '"plainTenant"'
          properties:
            externalId: .externalId
            url: 'if .url == null or .url == "" then null elif (.url | startswith("http://") or startswith("https://")) then .url else "https://" + .url end'
            createdAt: .createdAt.iso8601
            updatedAt: .updatedAt.iso8601
  - kind: user
    selector:
      query: "true"
      pageSize: 100
    port:
      entity:
        mappings:
          identifier: .id
          title: .fullName // .publicName // .email
          blueprint: '"plainUser"'
          properties:
            email: .email
            publicName: .publicName
            status: .status
            role: .role.name
  - kind: machine-user
    selector:
      query: "true"
      pageSize: 100
      excludeDeleted: false
    port:
      entity:
        mappings:
          identifier: .id
          title: .fullName // .publicName
          blueprint: '"plainMachineUser"'
          properties:
            publicName: .publicName
            description: .description
            type: .type
            isCustomAgent: .isCustomAgent
            isAssignableToThreads: .isAssignableToThreads
            isDeleted: .isDeleted
            createdAt: .createdAt.iso8601
            updatedAt: .updatedAt.iso8601
  - kind: customer
    selector:
      query: "true"
      pageSize: 100
    port:
      entity:
        mappings:
          identifier: .id
          title: .fullName // .shortName // .email.email
          blueprint: '"plainCustomer"'
          properties:
            externalId: .externalId
            email: .email.email
            shortName: .shortName
            createdAt: .createdAt.iso8601
            updatedAt: .updatedAt.iso8601
          relations:
            company: .company.id
            tenants: "[.tenantMemberships.edges[]?.node.tenant.id]"
  - kind: thread
    selector:
      query: "true"
      pageSize: 100
      excludeDoneThreads: false
    port:
      entity:
        mappings:
          identifier: .id
          title: .title // .ref
          blueprint: '"plainThread"'
          properties:
            ref: .ref
            externalId: .externalId
            description: .description
            status: .status
            priority: .priority
            tier: .tier.name
            assigneeType: .assignedTo.__typename
            labels: "[.labels[]?.labelType.name]"
            productArea: '([.threadFields[]? | select(.key == "product_area") | .stringValue] | first) // ""'
            fields: '[.threadFields[]? | .key + "=" + ((.stringValue // .numberValue // .booleanValue) | tostring)] | join(", ")'
            createdAt: .createdAt.iso8601
            updatedAt: .updatedAt.iso8601
          relations:
            customer: .customer.id
            tenant: .tenant.id
            assignee: if .assignedTo.__typename == "User" then .assignedTo.id else null end
            machineAssignee: if .assignedTo.__typename == "MachineUser" then .assignedTo.id else null end
  - kind: thread-message
    selector:
      query: "true"
      pageSize: 100
      excludeDoneThreads: false
    port:
      entity:
        mappings:
          identifier: .id
          title: '(.entry.__typename // "Message") + (if .llmText then ": " + .llmText[0:80] else "" end)'
          blueprint: '"plainThreadMessage"'
          properties:
            text: .llmText
            entryType: .entry.__typename
            timestamp: .timestamp.iso8601
            actorType: .actor.__typename
            actorId: .actor.user.id // .actor.customer.id // .actor.machineUser.id
          relations:
            thread: .threadId
  - kind: discussion
    selector:
      query: "true"
      pageSize: 100
      excludeDoneThreads: false
      excludeAiDiscussions: false
    port:
      entity:
        mappings:
          identifier: .id
          title: .title
          blueprint: '"plainDiscussion"'
          properties:
            status: .status
            agentStatus: .agentStatus
            visibility: .visibility
            isUnread: .isUnread
            channel: 'if .channelDetails == null then null elif .channelDetails.__typename == "ThreadDiscussionSlackChannelDetails" then "SLACK" elif .channelDetails.__typename == "ThreadDiscussionEmailChannelDetails" then "EMAIL" elif .channelDetails.__typename == "ThreadDiscussionCursorWorkspaceBackgroundAgentChannelDetails" then "CURSOR" elif .channelDetails.__typename == "ThreadDiscussionAgentSessionChannelDetails" then "AGENT_SESSION" else .channelDetails.__typename end'
            slackChannelName: .channelDetails.slackChannelName
            slackMessageLink: .channelDetails.slackMessageLink
            emailRecipients: .channelDetails.emailRecipients
            createdAt: .createdAt.iso8601
            updatedAt: .updatedAt.iso8601
            lastActivityAt: .lastActivityAt.iso8601
            resolvedAt: .resolvedAt.iso8601
            createdByType: .createdBy.__typename
            createdById: .createdBy.userId // .createdBy.customerId // .createdBy.machineUserId // .createdBy.systemId
          relations:
            thread: .threadId
  - kind: discussion-message
    selector:
      query: "true"
      pageSize: 100
      excludeDoneThreads: false
      excludeAiDiscussions: false
    port:
      entity:
        mappings:
          identifier: .id
          title: '(.type // "Message") + (if .text then ": " + .text[0:80] else "" end)'
          blueprint: '"plainDiscussionMessage"'
          properties:
            text: .text
            messageType: .type
            slackMessageLink: .slackMessageLink
            timestamp: .createdAt.iso8601
            authorType: .createdBy.__typename
            authorId: .createdBy.userId // .createdBy.customerId // .createdBy.machineUserId // .createdBy.systemId
          relations:
            thread: .threadId
            discussion: .threadDiscussionId

Monitoring and sync status

To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.

Mapping & selectors per resource

Use the explorer below to view sample payloads and the resulting Port entities for each resource type.

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: company
    selector:
      query: "true"
      pageSize: 100
    port:
      entity:
        mappings:
          identifier: .id
          title: .name
          blueprint: '"plainCompany"'
          properties:
            domainName: .domainName
            createdAt: .createdAt.iso8601
            updatedAt: .updatedAt.iso8601

{
  "id": "c_01HQEXAMPLECOMPANY",
  "name": "Acme Corp",
  "domainName": "acme.com",
  "createdAt": { "iso8601": "2024-01-15T10:00:00.000Z" },
  "updatedAt": { "iso8601": "2024-06-01T12:30:00.000Z" }
}

{
  "identifier": "c_01HQEXAMPLECOMPANY",
  "title": "Acme Corp",
  "blueprint": "plainCompany",
  "properties": {
    "domainName": "acme.com",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-06-01T12:30:00.000Z"
  },
  "relations": {}
}

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: tenant
    selector:
      query: "true"
      pageSize: 100
    port:
      entity:
        mappings:
          identifier: .id
          title: .name
          blueprint: '"plainTenant"'
          properties:
            externalId: .externalId
            url: 'if .url == null or .url == "" then null elif (.url | startswith("http://") or startswith("https://")) then .url else "https://" + .url end'
            createdAt: .createdAt.iso8601
            updatedAt: .updatedAt.iso8601

{
  "id": "t_01HQEXAMPLETENANT",
  "name": "Acme Production",
  "externalId": "acme-prod",
  "url": "acme.com",
  "createdAt": { "iso8601": "2024-02-01T09:00:00.000Z" },
  "updatedAt": { "iso8601": "2024-05-20T14:00:00.000Z" }
}

{
  "identifier": "t_01HQEXAMPLETENANT",
  "title": "Acme Production",
  "blueprint": "plainTenant",
  "properties": {
    "externalId": "acme-prod",
    "url": "https://acme.com",
    "createdAt": "2024-02-01T09:00:00.000Z",
    "updatedAt": "2024-05-20T14:00:00.000Z"
  },
  "relations": {}
}

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: user
    selector:
      query: "true"
      pageSize: 100
    port:
      entity:
        mappings:
          identifier: .id
          title: .fullName // .publicName // .email
          blueprint: '"plainUser"'
          properties:
            email: .email
            publicName: .publicName
            status: .status
            role: .role.name

{
  "id": "u_01HQEXAMPLEUSER",
  "fullName": "Alex Rivera",
  "publicName": "Alex",
  "email": "alex@company.com",
  "status": "ONLINE",
  "role": { "id": "r_01HQEXAMPLEROLE", "name": "Admin", "key": "admin" }
}

{
  "identifier": "u_01HQEXAMPLEUSER",
  "title": "Alex Rivera",
  "blueprint": "plainUser",
  "properties": {
    "email": "alex@company.com",
    "publicName": "Alex",
    "status": "ONLINE",
    "role": "Admin"
  },
  "relations": {}
}

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: machine-user
    selector:
      query: "true"
      pageSize: 100
      excludeDeleted: false
    port:
      entity:
        mappings:
          identifier: .id
          title: .fullName // .publicName
          blueprint: '"plainMachineUser"'
          properties:
            publicName: .publicName
            description: .description
            type: .type
            isCustomAgent: .isCustomAgent
            isAssignableToThreads: .isAssignableToThreads
            isDeleted: .isDeleted
            createdAt: .createdAt.iso8601
            updatedAt: .updatedAt.iso8601

{
  "id": "mu_01HQEXAMPLEMACHINE",
  "fullName": "Port Sync Bot",
  "publicName": "Port Sync",
  "description": "API bot used by the Port Ocean integration",
  "type": "API_USER",
  "isCustomAgent": false,
  "isAssignableToThreads": false,
  "isDeleted": false,
  "createdAt": { "iso8601": "2024-03-01T08:00:00.000Z" },
  "updatedAt": { "iso8601": "2024-03-01T08:00:00.000Z" }
}

{
  "identifier": "mu_01HQEXAMPLEMACHINE",
  "title": "Port Sync Bot",
  "blueprint": "plainMachineUser",
  "properties": {
    "publicName": "Port Sync",
    "description": "API bot used by the Port Ocean integration",
    "type": "API_USER",
    "isCustomAgent": false,
    "isAssignableToThreads": false,
    "isDeleted": false,
    "createdAt": "2024-03-01T08:00:00.000Z",
    "updatedAt": "2024-03-01T08:00:00.000Z"
  },
  "relations": {}
}

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: customer
    selector:
      query: "true"
      pageSize: 100
    port:
      entity:
        mappings:
          identifier: .id
          title: .fullName // .shortName // .email.email
          blueprint: '"plainCustomer"'
          properties:
            externalId: .externalId
            email: .email.email
            shortName: .shortName
            createdAt: .createdAt.iso8601
            updatedAt: .updatedAt.iso8601
          relations:
            company: .company.id
            tenants: "[.tenantMemberships.edges[]?.node.tenant.id]"

{
  "id": "c_01HQEXAMPLECUSTOMER",
  "externalId": "cust-42",
  "fullName": "Jamie Lee",
  "shortName": "Jamie",
  "email": { "email": "jamie@acme.com" },
  "company": { "id": "c_01HQEXAMPLECOMPANY" },
  "tenantMemberships": {
    "edges": [
      { "node": { "tenant": { "id": "t_01HQEXAMPLETENANT" } } }
    ]
  },
  "createdAt": { "iso8601": "2024-04-10T11:00:00.000Z" },
  "updatedAt": { "iso8601": "2024-06-15T16:00:00.000Z" }
}

{
  "identifier": "c_01HQEXAMPLECUSTOMER",
  "title": "Jamie Lee",
  "blueprint": "plainCustomer",
  "properties": {
    "externalId": "cust-42",
    "email": "jamie@acme.com",
    "shortName": "Jamie",
    "createdAt": "2024-04-10T11:00:00.000Z",
    "updatedAt": "2024-06-15T16:00:00.000Z"
  },
  "relations": {
    "company": "c_01HQEXAMPLECOMPANY",
    "tenants": ["t_01HQEXAMPLETENANT"]
  }
}

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: thread
    selector:
      query: "true"
      pageSize: 100
      excludeDoneThreads: false
    port:
      entity:
        mappings:
          identifier: .id
          title: .title // .ref
          blueprint: '"plainThread"'
          properties:
            ref: .ref
            externalId: .externalId
            description: .description
            status: .status
            priority: .priority
            tier: .tier.name
            assigneeType: .assignedTo.__typename
            labels: "[.labels[]?.labelType.name]"
            productArea: '([.threadFields[]? | select(.key == "product_area") | .stringValue] | first) // ""'
            fields: '[.threadFields[]? | .key + "=" + ((.stringValue // .numberValue // .booleanValue) | tostring)] | join(", ")'
            createdAt: .createdAt.iso8601
            updatedAt: .updatedAt.iso8601
          relations:
            customer: .customer.id
            tenant: .tenant.id
            assignee: if .assignedTo.__typename == "User" then .assignedTo.id else null end
            machineAssignee: if .assignedTo.__typename == "MachineUser" then .assignedTo.id else null end

{
  "id": "th_01HQEXAMPLETHREAD",
  "ref": "T-1042",
  "externalId": null,
  "title": "Cannot reset password",
  "description": "Customer cannot reset their password from the login page.",
  "status": "TODO",
  "priority": 2,
  "tier": { "id": "tier_01HQEXAMPLE", "name": "Enterprise" },
  "labels": [{ "labelType": { "name": "bug" } }],
  "threadFields": [
    { "key": "product_area", "stringValue": "auth" }
  ],
  "customer": { "id": "c_01HQEXAMPLECUSTOMER" },
  "tenant": { "id": "t_01HQEXAMPLETENANT" },
  "assignedTo": { "__typename": "User", "id": "u_01HQEXAMPLEUSER" },
  "createdAt": { "iso8601": "2024-06-20T09:15:00.000Z" },
  "updatedAt": { "iso8601": "2024-06-20T10:00:00.000Z" }
}

{
  "identifier": "th_01HQEXAMPLETHREAD",
  "title": "Cannot reset password",
  "blueprint": "plainThread",
  "properties": {
    "ref": "T-1042",
    "externalId": null,
    "description": "Customer cannot reset their password from the login page.",
    "status": "TODO",
    "priority": 2,
    "tier": "Enterprise",
    "assigneeType": "User",
    "labels": ["bug"],
    "productArea": "auth",
    "fields": "product_area=auth",
    "createdAt": "2024-06-20T09:15:00.000Z",
    "updatedAt": "2024-06-20T10:00:00.000Z"
  },
  "relations": {
    "customer": "c_01HQEXAMPLECUSTOMER",
    "tenant": "t_01HQEXAMPLETENANT",
    "assignee": "u_01HQEXAMPLEUSER",
    "machineAssignee": null
  }
}

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: thread-message
    selector:
      query: "true"
      pageSize: 100
      excludeDoneThreads: false
    port:
      entity:
        mappings:
          identifier: .id
          title: '(.entry.__typename // "Message") + (if .llmText then ": " + .llmText[0:80] else "" end)'
          blueprint: '"plainThreadMessage"'
          properties:
            text: .llmText
            entryType: .entry.__typename
            timestamp: .timestamp.iso8601
            actorType: .actor.__typename
            actorId: .actor.user.id // .actor.customer.id // .actor.machineUser.id
          relations:
            thread: .threadId

{
  "id": "te_01HQEXAMPLETIMELINE",
  "threadId": "th_01HQEXAMPLETHREAD",
  "llmText": "Hi, I cannot reset my password from the login page.",
  "entry": { "__typename": "EmailEntry" },
  "timestamp": { "iso8601": "2024-06-20T09:15:30.000Z" },
  "actor": {
    "__typename": "CustomerActor",
    "customer": { "id": "c_01HQEXAMPLECUSTOMER" }
  }
}

{
  "identifier": "te_01HQEXAMPLETIMELINE",
  "title": "EmailEntry: Hi, I cannot reset my password from the login page.",
  "blueprint": "plainThreadMessage",
  "properties": {
    "text": "Hi, I cannot reset my password from the login page.",
    "entryType": "EmailEntry",
    "timestamp": "2024-06-20T09:15:30.000Z",
    "actorType": "CustomerActor",
    "actorId": "c_01HQEXAMPLECUSTOMER"
  },
  "relations": {
    "thread": "th_01HQEXAMPLETHREAD"
  }
}

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: discussion
    selector:
      query: "true"
      pageSize: 100
      excludeDoneThreads: false
      excludeAiDiscussions: false
    port:
      entity:
        mappings:
          identifier: .id
          title: .title
          blueprint: '"plainDiscussion"'
          properties:
            status: .status
            agentStatus: .agentStatus
            visibility: .visibility
            isUnread: .isUnread
            channel: 'if .channelDetails == null then null elif .channelDetails.__typename == "ThreadDiscussionSlackChannelDetails" then "SLACK" elif .channelDetails.__typename == "ThreadDiscussionEmailChannelDetails" then "EMAIL" elif .channelDetails.__typename == "ThreadDiscussionCursorWorkspaceBackgroundAgentChannelDetails" then "CURSOR" elif .channelDetails.__typename == "ThreadDiscussionAgentSessionChannelDetails" then "AGENT_SESSION" else .channelDetails.__typename end'
            slackChannelName: .channelDetails.slackChannelName
            slackMessageLink: .channelDetails.slackMessageLink
            emailRecipients: .channelDetails.emailRecipients
            createdAt: .createdAt.iso8601
            updatedAt: .updatedAt.iso8601
            lastActivityAt: .lastActivityAt.iso8601
            resolvedAt: .resolvedAt.iso8601
            createdByType: .createdBy.__typename
            createdById: .createdBy.userId // .createdBy.customerId // .createdBy.machineUserId // .createdBy.systemId
          relations:
            thread: .threadId

{
  "id": "td_01HQEXAMPLEDISCUSSION",
  "threadId": "th_01HQEXAMPLETHREAD",
  "title": "Internal notes",
  "status": "OPEN",
  "agentStatus": "IDLE",
  "visibility": "WORKSPACE",
  "isUnread": false,
  "channelDetails": {
    "__typename": "ThreadDiscussionSlackChannelDetails",
    "slackChannelName": "support-internal",
    "slackMessageLink": "https://company.slack.com/archives/C012345/p1234567890"
  },
  "createdBy": { "__typename": "UserActor", "userId": "u_01HQEXAMPLEUSER" },
  "createdAt": { "iso8601": "2024-06-20T09:20:00.000Z" },
  "updatedAt": { "iso8601": "2024-06-20T09:25:00.000Z" },
  "lastActivityAt": { "iso8601": "2024-06-20T09:25:00.000Z" },
  "resolvedAt": null
}

{
  "identifier": "td_01HQEXAMPLEDISCUSSION",
  "title": "Internal notes",
  "blueprint": "plainDiscussion",
  "properties": {
    "status": "OPEN",
    "agentStatus": "IDLE",
    "visibility": "WORKSPACE",
    "isUnread": false,
    "channel": "SLACK",
    "slackChannelName": "support-internal",
    "slackMessageLink": "https://company.slack.com/archives/C012345/p1234567890",
    "emailRecipients": null,
    "createdAt": "2024-06-20T09:20:00.000Z",
    "updatedAt": "2024-06-20T09:25:00.000Z",
    "lastActivityAt": "2024-06-20T09:25:00.000Z",
    "resolvedAt": null,
    "createdByType": "UserActor",
    "createdById": "u_01HQEXAMPLEUSER"
  },
  "relations": {
    "thread": "th_01HQEXAMPLETHREAD"
  }
}

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: discussion-message
    selector:
      query: "true"
      pageSize: 100
      excludeDoneThreads: false
      excludeAiDiscussions: false
    port:
      entity:
        mappings:
          identifier: .id
          title: '(.type // "Message") + (if .text then ": " + .text[0:80] else "" end)'
          blueprint: '"plainDiscussionMessage"'
          properties:
            text: .text
            messageType: .type
            slackMessageLink: .slackMessageLink
            timestamp: .createdAt.iso8601
            authorType: .createdBy.__typename
            authorId: .createdBy.userId // .createdBy.customerId // .createdBy.machineUserId // .createdBy.systemId
          relations:
            thread: .threadId
            discussion: .threadDiscussionId

{
  "id": "tdm_01HQEXAMPLEMSG",
  "threadId": "th_01HQEXAMPLETHREAD",
  "threadDiscussionId": "td_01HQEXAMPLEDISCUSSION",
  "text": "Checking auth service logs for this customer.",
  "type": "OUTBOUND",
  "slackMessageLink": "https://company.slack.com/archives/C012345/p1234567891",
  "createdBy": { "__typename": "UserActor", "userId": "u_01HQEXAMPLEUSER" },
  "createdAt": { "iso8601": "2024-06-20T09:25:00.000Z" }
}

{
  "identifier": "tdm_01HQEXAMPLEMSG",
  "title": "OUTBOUND: Checking auth service logs for this customer.",
  "blueprint": "plainDiscussionMessage",
  "properties": {
    "text": "Checking auth service logs for this customer.",
    "messageType": "OUTBOUND",
    "slackMessageLink": "https://company.slack.com/archives/C012345/p1234567891",
    "timestamp": "2024-06-20T09:25:00.000Z",
    "authorType": "UserActor",
    "authorId": "u_01HQEXAMPLEUSER"
  },
  "relations": {
    "thread": "th_01HQEXAMPLETHREAD",
    "discussion": "td_01HQEXAMPLEDISCUSSION"
  }
}

Set up live events

This integration supports live events, allowing real-time updates to your software catalog without waiting for the next scheduled sync.

Note that different events are supported depending on the resource type.

Hosted by Port

Live events base URL

For integrations installed using the Hosted by Port method, you can obtain the live events base URL from the Get an integration API. The response includes liveEventsUuid and liveEventsIngestHostname in the appSpec section.

Call the endpoint with your integration's identifier:

curl -X GET \
  'https://api.port.io/v1/integration/<INTEGRATION_IDENTIFIER>' \
  -H 'Authorization: Bearer <PORT_ACCESS_TOKEN>'

Selecting a Port API URL by account region

The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:

• EU (app.port.io) → https://api.port.io
• US (app.us.port.io) → https://api.us.port.io

In the response, look for the following fields under spec.appSpec:

{
  "spec": {
    "appSpec": {
      "liveEventsUuid": "abcdefghijk",
      "liveEventsIngestHostname": "ingest.ocean.getport.io"
    }
  }
}

Combine them to build the live events base URL:

https://<liveEventsIngestHostname>/live-events/<liveEventsUuid>

For example, with the values above, the live events base URL is:

https://ingest.ocean.getport.io/live-events/abcdefghijk

This is the same URL configured for the integration.

Self-hosted

BaseUrl & webhook configuration

To enable real-time updates of the data in your software catalog, you need to define the liveEvents.baseUrl parameter.
This parameter should be set to the URL of your Plain integration instance, which needs to have the option to setup webhooks via HTTP requests/receive HTTP requests, so ensure the network is configured accordingly.

• If Plain and the integration are in the same cluster/network: Use an internal URL (e.g., a Kubernetes service DNS name).
  For Kubernetes deployments, create a service to expose the integration pod and use the service URL as liveEvents.baseUrl. If both the source system and integration are in the same cluster, an internal ClusterIP service is sufficient.
• If Plain is external to the integration's network: The integration must be exposed via an ingress, load balancer, or public URL that Plain can reach.

Scaling for high-volume, self-hosted deployments

If you're running high volumes of live events in a self-hosted deployment and want better reliability, event durability, or horizontal scalability, you can optionally set up Port's dedicated live events infrastructure. See live events at scale for details.

If liveEvents.baseUrl is not provided, the integration will continue to function correctly. In such a configuration, to retrieve the latest information from the target system, the scheduledResyncInterval parameter has to be set, or a manual resync will need to be triggered through Port's UI.

Debugging local integrations

To test webhooks or live event delivery to your local environment, expose your local pod or service to the internet using ngrok (e.g. ngrok http http://localhost:8000)

Securing Your Webhooks

The integration.secrets.webhookSecret parameter secures your webhooks. If not provided, the integration will process webhooks without validating the source of the events.

Limitations

• Live events need an event listener that processes webhooks and a reachable liveEvents.baseUrl (or hosted-by-Port equivalent).
• Plain does not emit dedicated company, tenant, user, or machine-user webhooks. Those kinds update when related thread or customer events fire.
• Only the UK GraphQL host (https://core-api.uk.plain.com/graphql/v1) is known to resolve. Use apiUrl only if Plain adds another region.
• Customer tenants come from the first page of tenantMemberships (at most 100). That selection needs customerTenantMembership:read in addition to customer:read.
• The user query selects role, which needs roles:read in addition to user:read.
• Thread messages come from thread.timelineEntries, which needs timeline:read in addition to thread:read.
• Thread tier is mapped as a string (.tier.name), not a separate kind. Nested selection may need tier:read.
• A human thread assignee maps to assignee (plainUser). A machine assignee maps to machineAssignee (plainMachineUser). assigneeType stores the Plain __typename.
• A missing Plain permission fails that kind and logs the permission name. The other kinds still sync.