What the customer reference API and webhooks are for
A reference library is most useful when it agrees with the rest of your systems. If a customer changes in one place and not in the other, someone ends up copying data by hand, and the copy is wrong within a month.
lyynx gives you two ways to connect your reference data to systems you run yourself:
- A REST API that your code calls to read and write reference data.
- Outgoing webhooks that lyynx sends to your systems when something happens, so you do not have to keep asking.
These are building blocks for your own developers. This page describes what is available and how to use it carefully. The full reference is in the API documentation.
How the API works in lyynx
What you can read and write
| Resource | Read | Write |
|---|---|---|
| Reference companies | Yes | Yes |
| Reference contacts | Yes | Yes |
| Tags | Yes | Yes |
| Contact requests | Yes | No |
The first three are the core of the customer reference library. Contact requests are read only, so your systems can see what prospects have asked for but cannot create or change a request on anyone's behalf.
Personal access tokens
You authenticate with a personal access token. Each token is scoped in two ways:
- To one company. A token works for a single company's data, even if the person who created it belongs to more than one.
- To abilities. You choose what the token may do: read or write for references, contacts and tags, and read for contact requests.
A token that only needs to list references for a report should have read abilities and nothing else.
| Token name | Company | Abilities | Created by |
|---|---|---|---|
| Reporting export | Demo Co. | References: read Contacts: read Contact requests: read | Alex Example |
| Library sync | Demo Co. | References: write Contacts: write Tags: write | Sam Sample |
| Tag audit | Demo Co. | Tags: read | Riley Demo |
OpenAPI documentation
The API is described in OpenAPI format in the documentation linked above. Use it as the source of truth for paths, fields and responses. This page deliberately does not repeat them.
Rate limits
Requests are rate limited. Write your client so that it slows down and retries when it reaches the limit, and avoid tight loops that fetch the same data repeatedly.
How outgoing webhooks work
A webhook is a message lyynx sends to an address you control when something happens in your account. Your system receives it and acts on it, with no need to poll the API on a timer.
Every outgoing webhook is signed with HMAC. The signature is computed from the message and a secret shared between lyynx and your receiving system. Your code computes the same signature on arrival and compares the two. If they do not match, the message did not come from lyynx or was changed on the way, and you should discard it.
Check the signature before you do anything else with a delivery. An unsigned or wrongly signed message should never reach your business logic.
How the API respects the advocate
An API is a second door into the same data, so it has to hold to the same promises as the screens people use.
- Least access by design. Tokens are limited to one company and to named abilities. A system that only needs to read cannot write.
- No outreach by script. Contact requests are read only. Code cannot generate requests to advocates, which keeps a person in the loop whenever a customer is asked for their time.
- Advocate data is personal data. Anything you copy out of lyynx becomes your responsibility. If an advocate hides a detail or revokes consent, your downstream copy needs to follow.
Who uses it
- Developers and operations teams who keep internal systems in step with the reference library.
- Data and analytics teams who want reference data in their own reporting.
- Customer marketing, who decide which tags and fields matter and ask for the connection to be built.
Practical tips
- One token per purpose. Give each script or system its own token with only the abilities it needs. If one is exposed, only one thing has to be replaced.
- Name tokens for what they do. "Reporting export" tells the next admin why it exists.
- Keep tokens and webhook secrets out of source files. Store them the way you store any other credential.
- Start read only. Build and test against read abilities first. Add write when you trust the code.
- Agree on tags before you sync them. Writing tags from another system will multiply a messy list quickly. Settle your reference taxonomy first.
- Make webhook handling safe to repeat. Write your receiver so that processing the same delivery twice does no harm.
- Respond quickly. Acknowledge the delivery, then do slow work in the background.
- For a one-time load, use the import. If you only need to bring in an existing list once, the CSV import with the customer reference library template is simpler than writing code.