Integration Endpoints
Part of: Connection Profiles — the connection says which system and how to authenticate; an endpoint says which operation on it.
An endpoint is one named operation on an external system: its method, its path, its headers, and the body it sends. Workflow actions point at an endpoint by name rather than carrying a URL and a body of their own, so the contract with the external system lives in one place and every change to it is recorded.
Why endpoints exist
Most integrations look the same in practice. One system, one set of credentials, and several operations against it: a receipt, a consume, a ship notice, a status update. Each operation has its own URL and its own body, but they all share the connection.
Endpoints match that shape: they sit between the connection and the workflow action, as the three-layer model describes.
The alternative, configuring the URL and body directly on each workflow action, has a problem that only shows up months later. Workflows are not versioned, so when a delivery starts failing there is no record of what the request used to look like or who changed it. Endpoints keep a version history for exactly that question.
Permissions
| Action | Required Role |
|---|---|
| View and manage endpoints | Admin |
Endpoints belong to their connection profile and inherit its visibility. Managing them is admin-only, like the profiles themselves.
Creating an Endpoint
Endpoints live on a connection profile, so start there.
- Open the Connection Profiles tab of the Integrations page and click the profile for the system you are integrating with. If it does not exist yet, create it first: see Connection Profiles.
- Click the Endpoints card at the top of the page, or Add endpoint in its Actions menu. You can also start from the Connection Profiles list itself, with Add > Endpoint, which asks which connection the endpoint belongs to before opening the same form.
- Fill in the form:
| Field | Description |
|---|---|
| Name | What this operation is called, for example "Consume item" or "Ship notice". Names must be unique within the profile. This is what appears in the workflow action picker |
| Description | Optional notes, such as which vendor document describes this call |
| Method | POST, GET, PUT, PATCH, or DELETE |
| Path | The path this operation is called at, including the query string if it is part of the operation. If the profile has a base URL, the path is joined to it; if not, enter the full URL here |
| Headers | Headers specific to this operation. Headers the whole connection needs belong on the profile instead |
| Body | The request body, written as a template. Leave it empty for an operation that sends nothing, such as a GET |
| Body content type | JSON, XML, or plain text. This sets the request Content-Type |
As you type the path, a Sends to: line shows the full URL the endpoint will call, so a base URL that does not join the way you expected is visible immediately. The path has to resolve to a full http or https URL: if the connection has no base URL, enter the whole URL here.
There is no change note when creating an endpoint, since there is nothing yet to describe a change against. When you save an edit that changes what the endpoint sends, Tagnet prompts for an optional comment (for example, "Added the lot number") before saving; cancel the prompt and the save is aborted. Saves that only touch the name or description skip the prompt, since they do not create a new version.
- Save.
Writing the body
The body is a Scriban template rendered against the event that triggered the workflow. The same variables available in message templates are available here, so {{ filtered_tags[0].epc }} and {{ scan_event.device_name }} work the way they do elsewhere.
The editor's side strip includes the same starter catalog as message templates, filtered to the selected content type. Applying a starter replaces the editor content, with a confirmation if you have already written something.
Template expressions are not allowed in the path. A URL is matched against the external system's routing table and a rendered value in it usually means a delivery goes somewhere unintended. Put the value in the body, or in a query string that is fixed for this operation.
Headers and credentials
Credential-shaped header names are refused on an endpoint: any name containing auth, token, secret, cookie, credential, or password, plus qualified key headers such as X-Api-Key or Ocp-Apim-Subscription-Key. A name that merely ends in -Key, such as Idempotency-Key or X-Correlation-Key, is routing metadata and saves normally.
Authentication comes from the connection profile and is added at send time, which is what keeps a credential out of stored delivery records. If a system needs a fixed API key, configure it as the profile's authentication mode, or add it as a secret header, rather than as an endpoint header. A secret header rides on every request through the connection the same way the mode's own credential does, which is how an endpoint gets a second credential the mode alone can't carry, such as a static API key alongside a token-endpoint bearer token.
A request preview, whether on this endpoint's current version or an earlier one in the Versions tab, lists the connection's secret headers by name with the value masked, so you can confirm one is attached without exposing what it holds.
Versions
Every change to what an endpoint sends creates a new version. Changes to the name or description do not, because they do not change the request.
A version records the method, path, headers, body, content type, and the template engine used to render the body, along with who saved it and when, plus any comment. History is append-only: nothing is ever edited or removed.
Open an endpoint and switch to the Versions tab to see the history. Each row can be expanded to show that version's request exactly as it went on the wire.
Rolling back
Click Roll back on any earlier version to restore what it sent. The restored configuration is appended as a new version rather than replacing the current one, so the history stays linear and the fact that a rollback happened is itself part of the record.
Workflows pick up the change on their next run. Deliveries already queued keep the body they were rendered with, since the body is rendered once at queue time.
Testing an Endpoint
Setup is exactly when there is no live scan data to try an integration with, and when the external system's expectations are least certain. Test endpoint in the actions menu closes that gap.
The dialog shows the request the endpoint would make, with its body rendered against one of two sources:
- Sample data: synthetic values, safe to send. Identifiers are prefixed
SAMPLE-(SAMPLE-ITEM-001,SAMPLE-0001, and so on) so anything the test creates on the far side is easy to find and remove. - Real data: inventory items from this system. Search for one or more items in Add inventory item, by instance id or item id; each item you add becomes one tag in the rendered payload, carrying its real custom field values, location, catalog data, and EPC. Device is optional, since it only fills
scan_event, useful when the body reads something likescan_event.device_namebut nothing else about the device matters for this test. No scan happened, sotag.movementcomes from a sample rule (statusMoved, originSAMPLE-ORIGIN, destination the item's current location, transaction typeMOVE) and carries no transaction or correlation id.
An item with no active RFID tag still renders. It gets a synthesized, format-plausible EPC and is_mapped comes through false, and its chip in the picker is marked · no tag so you can tell at a glance which items in the payload aren't actually tagged.
Note: Access scope applies to both pickers and to what the test can read. A device or item outside your scope simply doesn't turn up as a search result, the same restriction that governs everywhere else in Tagnet.
The body is editable, so you can adjust it to whatever the target actually expects before sending; edits made here are not saved to the endpoint. If a path in the body finds nothing, for example a typo or a custom field this particular item left blank, an info banner lists it by line number. Switching data sources after editing the body does not overwrite your edit; a small notice offers Re-render instead, so pulling in the new selection is deliberate.
Send test request puts one real request on the wire using the profile's real credentials and shows what came back: the status code, how long it took, and the response body.
Sending real data
A real-data send is a live payload, not a rehearsal: the request carries actual custom field values, locations, and EPCs, and nothing in the target system marks it as a test. Clicking Send test request with real data selected asks you to confirm first, naming how many items are included and the exact URL the request is going to.
Tagnet also records the send. Testing with real data writes an IntegrationTestSentWithRealData security event, with the target URL and the device and inventory item ids the payload was built from. A test run against sample data emits no event and asks for no confirmation.
The result distinguishes two very different failures:
- Not sent. The request never reached the target. A bad URL, a token that could not be acquired, or an unreachable host. The message names the specific problem.
- A non-2xx status. The target answered and rejected the request. The URL and the credentials are right; the payload is what needs work.
A test is one attempt. It is never recorded as a delivery, it is not retried, and a failing test does not affect the circuit breaker for real traffic to the same host, whether it was sent with sample data or real data.
Using an Endpoint in a Workflow
In either HTTP action, Send HTTP Request or HTTP Integration (durable), pick an endpoint from the Endpoint list. Each entry reads as connection profile, then endpoint name, then method, and the action shows the method and full URL of the one you select.
The action stores the endpoint's id, so renaming the endpoint later never breaks it. Each run uses whichever version is current at the moment it runs, which is what makes a rollback take effect without editing every workflow that calls the endpoint.
Once an endpoint is selected, the URL, headers, body, content type, and authentication all come from the endpoint. On a durable action nothing else is configured: retry and timeout come from the Integration policy, as they always have. A Send HTTP Request action keeps its own timeout and retry count, because those describe how hard that call tries rather than what the operation is, and the reply is still available to later actions. See the Integration Outbox guide for the durable action's delivery behavior.
Converting an existing action
Actions configured before endpoints existed carry their own URL and body, and on Send HTTP Request their own authentication as well. They keep working, and they remain editable, but the action dialog shows a banner explaining what is missing: no record of who changed the request, or when.
Click Save as endpoint in that banner to move the configuration into a managed endpoint on the connection profile the action already points at. The whole request moves, so what gets sent afterwards is identical to what was being sent before. The new endpoint is named after the action and can be renamed afterwards.
A Send HTTP Request action has to authenticate through a connection profile before it can convert, because the endpoint is created on that profile. An action still using an inline API key or bearer token needs that credential moved onto a profile first, as the profile's authentication mode or a secret header; an action with no authentication needs a profile with authentication None. One difference after conversion: the request also carries the profile's default headers, which a Send HTTP Request action's own configuration never sent. The banner says so when the chosen profile has any. Timeout and retry count stay on the action.
If the action's body came from a shared message template, conversion copies that template's current content into the endpoint as a one-time snapshot. The live link is gone from that point on: editing the shared template afterwards no longer changes what this action sends, because the endpoint owns its body. That is deliberate, and it is the trade for the endpoint's version history being a complete record.
One case cannot be converted automatically. An action whose body comes from a preceding Render Template action has no body of its own for the endpoint to own. Move that body into an endpoint template first, then convert.
Duplicating an Endpoint
Copy an endpoint from Copy in its row's Actions menu in the connection's Endpoints section, or Copy in the endpoint's own Actions menu. Most customer integrations are one system with several near-identical operations, so building the second one from the first is usually faster than starting over.
Either route opens the create form with everything filled in from the original: method, path, headers, body and content type, under the first free name (for example "Post movement (2)"). Nothing exists until you save, so a copy you change your mind about leaves nothing behind on the connection.
The copy starts its own version history at v1 rather than inheriting the original's, and its v1 records where it came from. It is a new operation that happened to start from another, and carrying someone else's change log would misattribute it.
Deleting an Endpoint
Click Delete in the actions menu. The confirmation lists any workflow actions that still send to this endpoint and warns that they will start failing on their next run.
Deleting is not blocked by usage, the same way connection profiles are not. Actions reference endpoints by id, so a referencing action fails at run time with a clear message rather than the delete being refused. Reassign or remove those actions before or immediately after deleting.
Deleting a connection profile deletes its endpoints too, including their version history. The confirmation says so explicitly.
Delivery Records
Deliveries in the Integration Outbox record which endpoint produced them. The endpoint name is stored on the delivery itself, so it still reads correctly after the endpoint is renamed or deleted.
On the delivery list, the Target column shows the profile and endpoint under the URL, and the filter panel has an Endpoint filter. That filter is usually the one that matters: a system with four operations tends to fail one operation at a time, not all of them at once.
Best Practices
- Name endpoints after the operation, not the URL. "Consume item" is what an operator recognizes in a picker;
/api/SystemQueue/EnQueueConsumeItemis not. - Set a base URL on the profile. It makes endpoint paths short and readable, and it means a TEST to PROD move is one field on the profile rather than an edit to every endpoint.
- Write a comment when you change a body. The version history answers "what changed" on its own; the comment answers "why", which is the part nobody remembers later.
- Test before wiring a workflow to it. A test send takes seconds and rules out the URL, the credentials, and the payload shape all at once.
- Roll back rather than retyping. Restoring a version is exact, and it leaves a record. Retyping what you think the old body was does neither.
Frequently Asked Questions
Q: Can two endpoints share a body template? A: Not directly. The endpoint owns its body deliberately, so that changing a contract means editing one thing in one place. If two operations genuinely send the same body, duplicate the endpoint and keep them independent; in practice they drift apart quickly.
Q: Does renaming an endpoint break the workflow actions using it? A: No. Actions reference endpoints by internal id. Deliveries already recorded keep the name they were sent under.
Q: Can I still configure a URL directly on an HTTP action? A: Only for actions that already do. New actions are endpoint-only. The reason is the version history: an inline configuration has none, and a request that changed with no record of the change is the hardest kind of integration failure to diagnose.
Q: What happens to queued deliveries if I edit an endpoint? A: Nothing. The body is rendered and the URL resolved when the delivery is queued, so a queued delivery retries exactly what it was created with. Only new deliveries use the new version.
Q: My endpoint needs a value in the URL, not the body. What now? A: If the value is fixed for that operation, put it in the path or query string directly. If it varies per event, create one endpoint per fixed variant. Rendering values into URLs is not supported.
Q: Why does the test dialog ask me to confirm before sending real data? A: Because the request is going to look like a real delivery to the target system: real custom field values, a real location, and a real EPC, with nothing marking it as a test. The confirmation names the URL and the item count so that's the last thing you see before it goes out, and the send is recorded as a security event for the same reason.