Connect other tools
A service desk is rarely alone. This page covers the three ways ServiceFlo works with your other systems:
- Another system does something in ServiceFlo, such as opening a ticket: the API, with an API key.
- ServiceFlo tells another system that something happened: a webhook.
- Another system gives a yes or no that a ticket is waiting for: an external approval.
It is the short version. The reference, with a worked Power Automate example, is power-automate.md.
Throughout, replace help.example.org with your site’s address.
1. An API key
The API is a set of web addresses a program can call to do what a person does in the browser. An API key is the password such a program uses.
Every key acts as one person: it sees and changes exactly what that person may, and
the audit log records its changes under their name. So first make an account for the
other system (a “service account”), as in Your first hour: call it
something like monitoring, and put it on the team whose tickets it works with. Do not
use a real colleague’s account: the key would stop working the day they leave.
Then, as a superuser:
- Open Settings › Installation › API keys and add one.
- What uses it: a name for you, such as “Monitoring alerts”.
- Acts as: the service account’s username.
- Only these workspaces: tick them to narrow the key further. Optional.
- Expires: leave empty for a key that never expires.
- Save. The next page shows the key, which starts with
sf_. It is shown once. Copy it now into the other system; ServiceFlo keeps only a scrambled copy and cannot show it again. A lost key is replaced by a new one.
To stop a key, untick In use on its page. Calls with it are refused from then on.
2. Open a ticket from another system
The other system sends the key in a header named X-API-Key. This opens a ticket in
the workspace whose short name (its “slug”) is it:
curl https://help.example.org/api/v1/tickets \
-H "X-API-Key: sf_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"workspace": "it",
"title": "Disk almost full on files01",
"description": "92% used at 09:14.",
"requester": "sam@example.org"
}'
requester is a username or an email address. An address ServiceFlo has not seen
before gets a guest account, as it would if the person had sent an email.
The answer is the new ticket, with its id. With that id the same key can go on to:
| Call | What it does |
|---|---|
GET /api/v1/tickets/{id} |
Read the ticket. |
POST /api/v1/tickets/{id}/notes |
Add a reply the requester is emailed, or an internal note. |
POST /api/v1/tickets/{id}/status |
Change the status, with an optional note. |
POST /api/v1/tickets/{id}/assign |
Give it to an agent, or to nobody. |
POST /api/v1/tickets/{id}/move |
Move it to another workspace. |
Every call is listed at https://help.example.org/api/v1/docs, with what each one
takes and returns. Its “Try it out” buttons run a call for real, as you if you are
signed in or with a key you give it.
If a call is refused:
| Answer | What it means |
|---|---|
401 |
The key is wrong, switched off or past its expiry date. |
403 |
The key works, but its person may not do this. The answer says why. |
400 or 422 |
Something in what was sent is missing or wrong: no such workspace, status or person, or a field left out. The answer names it. |
Devices, and the status page
Two more jobs other systems often do. Both use the same key.
Keep the list of devices up to date. A device-management or inventory tool sends its devices as rows, like the rows of a spreadsheet. A row whose asset tag or serial number is already known updates that asset; any other is added:
curl https://help.example.org/api/v1/assets/import \
-H "X-API-Key: sf_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"workspace": "it",
"dry_run": true,
"rows": [
{"name": "Front desk laptop", "type": "Laptop", "tag": "IT-01042", "serial_number": "C02XK1"}
]
}'
With "dry_run": true nothing is saved: the answer says what each row would do. Take
it out once the answer looks right. The key’s account must work in a workspace that
uses Assets.
Put a notice on the status page. A monitoring tool can say that a service is in trouble the moment it notices, and take the notice down when it recovers:
curl https://help.example.org/api/v1/status/incidents \
-H "X-API-Key: sf_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"title": "Email is slow",
"impact": "degraded",
"services": ["email"],
"message": "We are looking into it."
}'
impact is degraded, outage or maintenance. services are the services’ short
names, which GET /api/v1/status/services lists. The answer has the incident’s id;
to close it:
curl https://help.example.org/api/v1/status/incidents/12/updates \
-H "X-API-Key: sf_your_key_here" \
-H "Content-Type: application/json" \
-d '{"state": "resolved", "message": "Fixed: a full disk."}'
Everything sent this way is public: the status page shows it to anyone who can see the service. The key’s account needs the permission Can open, update and resolve service incidents, which a superuser gives it under Back office › People.
Problems
A problem is the cause behind several tickets: the faulty access point behind ten Wi-Fi complaints. A tool that spots such a pattern can log it and link the tickets:
curl https://help.example.org/api/v1/problems \
-H "X-API-Key: sf_your_key_here" \
-H "Content-Type: application/json" \
-d '{"workspace": "it", "title": "Access point firmware crashes"}'
With the id from the answer:
| Call | What it does |
|---|---|
PATCH /api/v1/problems/{id} |
Change only what you send: status, root_cause, workaround, known_error, priority, team, assignee. |
POST /api/v1/problems/{id}/notes |
Add a note for the people working on it. |
POST /api/v1/problems/{id}/tickets |
Link a ticket: {"ticket": 4821}. |
GET /api/v1/problems?open=true |
List the problems still open. |
The key’s account must work in a workspace that uses Problems.
3. Webhooks: tell another system
A webhook is a message ServiceFlo sends to a web address you choose, the moment
something happens. The other system must have an address that accepts a POST with a
JSON document. In Power Automate that is the “When an HTTP request is received”
trigger.
There are two ways to send one.
Every time something happens
A workspace admin opens Settings › Email and integrations › Webhooks and adds one:
- Name and Address: what it is for, and where to send.
- Signing secret: optional, but set one (see “Is it really from ServiceFlo?”).
- Tell it when: tick the events. For tickets: created, status changed, note or reply added, assignee changed, moved to another workspace, any other change, approval asked, and approval settled. For the status page: service incident opened, updated, and resolved.
- Include private: left unticked, private tickets and the text of internal notes are not sent.
The list shows when each webhook was last called and how it went, and every delivery is in the audit log.
Only when a rule matches
For “only new account requests” or “only urgent tickets from Finance”, use a routing rule. Open Settings › Automation › Routing and escalation rules, give the rule its conditions, and add the action Call a webhook, with the address and a secret.
What arrives
{
"event": "ticket.status_changed",
"sent_at": "2026-11-15T09:14:03+00:00",
"actor": "dana",
"ticket": { "id": 4821, "number": "...", "title": "...", "...": "..." },
"previous_status": "open",
"status": "resolved"
}
event says what happened; a rule’s webhook says rule.matched and names the rule.
The header X-ServiceFlo-Event repeats it.
A status-page event (incident.opened, incident.updated, incident.resolved) has no
ticket. It carries the incident (its title, impact, state and the services it
touches) and the update just posted. Status incidents are public and belong to no
workspace, so a webhook hears them whatever workspace it is narrowed to. This is how a
wall display or a chat channel can show what the status page says.
Is it really from ServiceFlo?
Anyone who learns the address could post to it. With a signing secret set, every
message carries a header X-ServiceFlo-Signature: sha256=.... It is a fingerprint
(an “HMAC SHA-256”) of the message body, made with the secret. The receiver makes the
same fingerprint with the same secret and compares: only someone who knows the secret
could have produced a match.
A webhook is sent once. If the other system is down or answers with an error, the message is not sent again. The webhook’s Last call and the audit log show what happened, and a rule’s webhook that fails leaves a note on the ticket. Do not rely on a webhook alone for something that must never be missed: have the other system also ask the API now and then.
4. An approval from another system
Some requests need a yes before the work starts. Usually a person gives it inside ServiceFlo. An external approval is one that another system gives instead: a Power Automate approval flow, or a finance system that checks a budget.
It joins the two halves above:
-
A service in the catalog is set to be approved in an external workflow. A ticket made from that service’s form then waits for it: the ticket’s Approvals card shows “External approval process” and its approval number.
-
A webhook with Approval asked ticked tells the other system. The message includes the ticket and the approval’s
id. -
The other system does its work, then answers with an API key:
curl https://help.example.org/api/v1/approvals/123/decide \ -H "X-API-Key: sf_your_key_here" \ -H "Content-Type: application/json" \ -d '{"approved": true, "comment": "Budget confirmed."}'A “no” (
"approved": false) must come with acommentsaying why.
GET /api/v1/approvals?state=pending&external=true lists the approvals still waiting,
for a system that prefers to ask than to be told.
Microsoft Power Automate and Teams
- Power Automate has a ready-made way in: import
https://help.example.org/api/v1/openapi-2.0.jsonas a custom connector, choose API key with the header nameX-API-Key, and each call above becomes an action. power-automate.md walks through an approval flow. - Teams cards and presence are separate from all of this and have settings of their own, listed in deployment.md.
Before you rely on it
- Each system has its own key and its own service account, so one can be stopped without the others.
- Each key is narrowed to the workspaces it needs.
- Every webhook has a signing secret, and the receiver checks it.
- The receiving addresses use
https://. - Someone knows where the keys are kept, and that a lost key cannot be shown again.