How to

Lookup endpoints

On this page

A lookup endpoint is an HTTPS URL that Conclude calls before an agent answers on a ticket. The agent can then read a record that your own system holds, such as a CRM entry. This page is for the builder who runs that service.

Configure the lookup

lookup:
  url: https://crm.example.com/conclude-enrich
  secret: crm_api_token
  on: [onCreate, onComment]
  timeout: 5s
  • url must use https. Any other scheme is refused
  • secret names an organization Secret, which Conclude sends as Authorization: Bearer <token>. An unknown name sends the request without the header. Secrets are encrypted records that belong to the organization. An organization administrator creates one through the internal organization API (POST /fapi/organization/<organization>/secrets), which authenticates with a cookie. The Dashboard has no page for them, and the per-app secrets dialog (/c app secrets) is a different store
  • on lists the events that fire the lookup. The events are onCreate, onComment, onEdit and onConclude. An empty list never fires
  • timeout is a duration such as 10s. The default is 5 seconds and the cap is 30 seconds. A value that Conclude cannot parse, or that is zero or negative, falls back to the default

Key types are in the connectors reference.

What Conclude sends

For each event listed in on, Conclude sends one POST to url with Content-Type: application/json and this body:

{"event": "onCreate", "activity": {"title": "Login fails after upgrade", "email": "sam@example.com"}}

activity.title is the ticket title, and activity.email is the initiator’s email address. Conclude omits either field when it is empty. It sends no other ticket data. It does not follow redirects, and a 3xx answer counts as a failure.

How the response is used

Only a 2xx status counts. Conclude reads at most 4 KB of the body and trims the whitespace. It then inserts the text unchanged into the agent’s system prompt, under a ## Customer context heading. The text sits after the ticket state and before the trigger description. See what the agent sees. Plain text and JSON both work. Conclude parses and filters nothing, so return only what the agent should read.

Security and failures

  • Conclude resolves the hostname when it validates the URL, and checks it again when the connection opens. DNS therefore cannot steer a lookup into an internal network. Conclude blocks loopback, private (RFC 1918 and IPv6 unique local), link-local, multicast, unspecified and carrier-grade NAT (100.64.0.0/10) addresses. It also blocks the IPv6 ranges 2001::/32 and 2002::/16
  • Conclude logs a timeout, a connection error, a blocked address or a non-2xx status. The agent then answers without lookup data
  • The bearer token lives in the Secret, not in the app YAML, so sharing the YAML does not expose it