Headless Mode
Turn off every message DevStride sends your customers and receive each one as a signed customer.message webhook instead, ready to send from your own domain and tool: the seven message kinds, their fields, the people copied on a reply, sample events, and what still happens.
On this page
In headless mode DevStride sends nothing to your customers. Every email it would have sent a requester (a staff reply, an acknowledgement, a status update, a sign-in link, an address confirmation) is delivered to your webhook endpoint instead, as one customer.message event. Your own tool sends it, from your own domain, in your own branding.
Everything else keeps working: inbound email still creates tickets, the API still works, SLA clocks keep running, and staff see and do exactly what they did before.
Before you turn it on#
- Create a webhook endpoint subscribed to
customer.message, and make sure it is enabled. Headless mode refuses to turn on without one, so customer messages can never go nowhere. - Verify signatures and deduplicate on the event
id, as for every webhook: see Verifying Signatures and Delivery, Retries & Ordering. - Turn on Headless mode in Settings → Service Desk → Customer communication, or with the settings API below. See Headless Mode for what administrators see.
While headless mode is on, DevStride also refuses to delete, disable or unsubscribe the last enabled endpoint receiving customer.message. Subscribe a second endpoint first, or turn headless mode off.
The customer.message event#
Each event is one message for one customer. subject, text and html are already written and ready to send. They contain no DevStride logo, image, button, footer or link. html is plain paragraphs and lists, plus, for a reply, the reply's own formatting. text is the same message with the tags removed.
| Field | Type | Description |
|---|---|---|
data.kind |
string | What the message is: one of the seven kinds below. |
data.message |
object | The facts specific to that kind (below). {} when there are none. |
data.itemNumber |
string or null | The ticket it is about, for example I4821. null for login_link, portal_redirect and contact_email_confirmation, which are about no single ticket. |
data.itemTitle |
string or null | That ticket's title. null when itemNumber is. |
data.requester |
object | Who to send it to: { "id", "email", "name" }. email is lower case; name can be null. Read when the message is sent, so it is always the requester's current address. |
data.participants |
array | reply only: the other people copied on the ticket, who receive the reply as well. Each is { "id", "email", "name" }, like requester. [] when nobody else should get it. Absent on every other kind. |
data.companyId |
string or null | The requester's company, or null. |
data.subject |
string | The subject line to use. |
data.text |
string | The message as plain text. |
data.html |
string | The message as HTML. |
Send it to data.requester.email, and a reply to each address in data.participants too (DevStride's own email puts them on Cc). Nothing else in the event needs to reach the customer.
The seven kinds#
kind |
Sent when | data.message |
What you do |
|---|---|---|---|
reply |
A customer-visible reply is added to a ticket by staff in DevStride, or by an automation (for example the auto-close notice), or by a customer other than the requester, such as someone copied on the ticket replying in the portal or by email. | commentId, attachments (an array of file URLs the reply links to or embeds). |
Send it. Report the outcome with a delivery receipt for commentId if you like. |
request_received |
A new ticket is created from a customer's email. | {} |
Send the acknowledgement, or drop it if your tool sends its own. |
request_confirmation |
A customer submitted a request DevStride holds until they confirm their email address. | verificationToken |
Ask the customer to confirm their address in your tool, then call the confirm API with the token. |
status_change |
A ticket moves to a status with a different customer-facing label. Not sent when Email customers on status change is off. | fromLabel (or null), toLabel |
Send it, or update your own portal instead. |
login_link |
A customer asked to sign in to the DevStride customer portal. | magicLinkUrl, otpCode |
Send it only if you still offer the DevStride portal. |
portal_redirect |
A customer asked to sign in at the wrong company's portal and is pointed to their own. | companyName, portalLoginUrl |
Send it only if you still offer the DevStride portal. |
contact_email_confirmation |
Staff changed a contact's email address, or resent its confirmation, and the new address has to prove it works. | confirmationToken |
Ask the customer to confirm the address in your tool, then call the contact email confirm API with the token. Until then the contact shows Unverified. |
The status labels are open, in_progress, awaiting_your_reply, solved and closed. The rendered text uses their display form: Open, In progress, Awaiting your reply, Solved, Closed.
login_link and portal_redirect carry DevStride portal addresses, and are sent only while the customer portal is open. If you close the portal (Customer portal off), they stop.
Origin, and your own replies#
origin follows the webhook rules:
- a
replyreadsmember, with the username of the member who wrote it inactorId(for an automation's reply, the automation's creator); - a
replya customer wrote readscustomer, with their requester id inactorId; - every other kind reads
system, withactorIdnull.
A reply you post through the API never comes back as a customer.message. A staff reply you record is one your tool already delivered, so DevStride does not hand it back to you to send again. The comment.created event for it still fires, with origin.kind api.
Samples#
A staff reply with an attachment:
{
"id": "4b8e2f1c-7d3a-5c9e-b1f0-2a6d8e4c9b17",
"type": "customer.message",
"apiVersion": "2026-10-16",
"occurredAt": "2026-10-24T15:12:40.218Z",
"organizationId": "8f14e45f-ceea-4e7a-9b1d-3c5a2f6e9d10",
"origin": {
"kind": "member",
"actorId": "jordan.lee",
"correlationId": "e3c1a7b9-2f4d-4e6a-9b8c-1d5f7a3e2c60"
},
"data": {
"kind": "reply",
"message": {
"commentId": "c2f7a9d1-6e3b-4a8c-b5d0-9e1f4a7c3b28",
"attachments": [
"https://media.example.com/attachments/printer-settings.png"
]
},
"itemNumber": "I4821",
"itemTitle": "Printer on floor 3 is offline",
"requester": {
"id": "7a3d9c2e-1b5f-4e8a-a6c4-3f9e2d7b1c05",
"email": "sam.rivera@example.com",
"name": "Sam Rivera"
},
"participants": [
{
"id": "2c8f4a1e-9b3d-4e7a-8f2c-6d1b5e9a3c47",
"email": "dana.whitfield@example.com",
"name": "Dana Whitfield"
}
],
"companyId": "5e9b1d3f-8c2a-4f6e-b7d1-0a4c8e2f6b93",
"subject": "Re: Printer on floor 3 is offline",
"text": "Thanks Sam, it is back online now.\n\nThe settings we changed are attached.",
"html": "<p>Thanks Sam, it is back online now.</p><p>The settings we changed are <a href=\"https://media.example.com/attachments/printer-settings.png\">attached</a>.</p>"
}
}
The other kinds have the same envelope, with origin.kind system and actorId null. Their data:
{
"kind": "request_received",
"message": {},
"itemNumber": "I4822",
"itemTitle": "VPN drops every hour",
"requester": { "id": "7a3d9c2e-1b5f-4e8a-a6c4-3f9e2d7b1c05", "email": "sam.rivera@example.com", "name": "Sam Rivera" },
"companyId": "5e9b1d3f-8c2a-4f6e-b7d1-0a4c8e2f6b93",
"subject": "We received your request “VPN drops every hour”",
"text": "We received your request “VPN drops every hour”.\n\nWe will reply as soon as we can.",
"html": "<p>We received your request “VPN drops every hour”.</p><p>We will reply as soon as we can.</p>"
}
{
"kind": "request_confirmation",
"message": { "verificationToken": "EXAMPLE-TOKEN-not-a-real-value" },
"itemNumber": "I4823",
"itemTitle": "New laptop for a starter",
"requester": { "id": "1c6e8a4b-3d9f-4b2e-8a7c-5f0d2b9e6a41", "email": "alex.kim@example.com", "name": null },
"companyId": null,
"subject": "Confirm your email to submit “New laptop for a starter”",
"text": "Please confirm your email address to submit your request “New laptop for a starter”.\n\nIf you did not make this request, you can ignore this message.",
"html": "<p>Please confirm your email address to submit your request “New laptop for a starter”.</p><p>If you did not make this request, you can ignore this message.</p>"
}
{
"kind": "status_change",
"message": { "fromLabel": "in_progress", "toLabel": "solved" },
"itemNumber": "I4821",
"itemTitle": "Printer on floor 3 is offline",
"requester": { "id": "7a3d9c2e-1b5f-4e8a-a6c4-3f9e2d7b1c05", "email": "sam.rivera@example.com", "name": "Sam Rivera" },
"companyId": "5e9b1d3f-8c2a-4f6e-b7d1-0a4c8e2f6b93",
"subject": "Your request \"Printer on floor 3 is offline\" is now Solved",
"text": "Your request “Printer on floor 3 is offline” is now Solved.",
"html": "<p>Your request “Printer on floor 3 is offline” is now Solved.</p>"
}
{
"kind": "login_link",
"message": { "magicLinkUrl": "https://app.devstride.com/portal/example-co/login/verify?token=EXAMPLE", "otpCode": "123456" },
"itemNumber": null,
"itemTitle": null,
"requester": { "id": "7a3d9c2e-1b5f-4e8a-a6c4-3f9e2d7b1c05", "email": "sam.rivera@example.com", "name": "Sam Rivera" },
"companyId": "5e9b1d3f-8c2a-4f6e-b7d1-0a4c8e2f6b93",
"subject": "Sign in to Example Co support",
"text": "Use this link to sign in to Example Co support: https://app.devstride.com/portal/example-co/login/verify?token=EXAMPLE\n\nOr enter this code: 123456\n\nIf you did not ask to sign in, you can ignore this message.",
"html": "<p>Use this link to sign in to Example Co support: https://app.devstride.com/portal/example-co/login/verify?token=EXAMPLE</p><p>Or enter this code: 123456</p><p>If you did not ask to sign in, you can ignore this message.</p>"
}
{
"kind": "portal_redirect",
"message": { "companyName": "Northwind", "portalLoginUrl": "https://app.devstride.com/portal/northwind/login" },
"itemNumber": null,
"itemTitle": null,
"requester": { "id": "7a3d9c2e-1b5f-4e8a-a6c4-3f9e2d7b1c05", "email": "sam.rivera@example.com", "name": "Sam Rivera" },
"companyId": "5e9b1d3f-8c2a-4f6e-b7d1-0a4c8e2f6b93",
"subject": "Your Example Co support portal",
"text": "Your requests with Example Co are in the Northwind support portal.\n\nSign in there: https://app.devstride.com/portal/northwind/login",
"html": "<p>Your requests with Example Co are in the Northwind support portal.</p><p>Sign in there: https://app.devstride.com/portal/northwind/login</p>"
}
{
"kind": "contact_email_confirmation",
"message": { "confirmationToken": "7a3d9c2e-1b5f-4e8a-a6c4-3f9e2d7b1c05.EXAMPLE-not-a-real-value" },
"itemNumber": null,
"itemTitle": null,
"requester": { "id": "7a3d9c2e-1b5f-4e8a-a6c4-3f9e2d7b1c05", "email": "sam.rivera@newmail.example.com", "name": "Sam Rivera" },
"companyId": "5e9b1d3f-8c2a-4f6e-b7d1-0a4c8e2f6b93",
"subject": "Please confirm your email address for Example Co support",
"text": "Please confirm this is your email address for Example Co support.\n\nIf you did not expect this message, you can ignore it.",
"html": "<p>Please confirm this is your email address for Example Co support.</p><p>If you did not expect this message, you can ignore it.</p>"
}
The portal addresses in the login_link and portal_redirect samples are illustrations; use the URLs exactly as they arrive.
People copied on a ticket#
Staff, and a customer's own email, can copy other people on a ticket. Each reply lists them in data.participants, read when the message is sent, oldest first, one entry per address:
| Field | Type | Description |
|---|---|---|
id |
string | The person's requester id. |
email |
string | Their address, in lower case. |
name |
string or null | Their name, or null. |
The list leaves out the requester, whoever wrote the reply, anyone blocked, erased or not yet confirmed, no-reply addresses, and members of your organization: everyone left in it should receive the reply. As for the requester, DevStride's own bounce records are not applied, because they say nothing about how your sending fares.
DevStride's own email passes a requester's emailed reply on to the copied people who weren't on it. Headless mode does not: a message the requester writes never becomes a customer.message.
Attachments#
A reply's files stay where DevStride stores them. data.message.attachments lists the public URLs the reply's html already links to or embeds, the same ones DevStride's own emails use. Link to them, or download and attach them in your tool. Files from your customers go in the other direction through the upload operations.
Who gets nothing#
No message is sent to a requester who is blocked or erased. Automatic notices (request_received, request_confirmation, status_change, contact_email_confirmation) are not sent to a no-reply address. The same rules govern DevStride's own email.
Settings API#
The four switches are one call, PATCH /service-desk/settings, with the Manage Service Desk Settings permission. Send only the keys you change.
| Key | Default | Meaning |
|---|---|---|
headlessMode |
false |
DevStride sends nothing to customers and emits customer.message instead. Turning it on is refused (400) unless an enabled endpoint is subscribed to customer.message. |
customerPortalEnabled |
true |
The customer portal is open. When false, it answers as if it did not exist, no email or message offers a portal link, and login_link and portal_redirect stop. |
helpCentreEnabled |
true |
The help centre (the portal's knowledge base) is open. When false, its pages answer as if they did not exist. |
notifyCustomerOnStatusChange |
true |
Customers are told when their ticket's customer-facing status changes, by email or, in headless mode, by a status_change message. |
curl -X PATCH "https://api.devstride.com/v1/organizations/$ORG_ID/service-desk/settings" \
-u "$DEVSTRIDE_API_KEY:$DEVSTRIDE_API_SECRET" \
-H "Content-Type: application/json" \
-d '{ "headlessMode": true, "customerPortalEnabled": false, "helpCentreEnabled": false }'
The response is the updated organization. To read the switches at any time, GET /v1/organizations/{organizationId} returns the organization under data, with serviceDeskHeadlessMode, serviceDeskCustomerPortalEnabled, serviceDeskHelpCentreEnabled and serviceDeskNotifyCustomerOnStatusChange and their defaults filled in.
What still happens in headless mode#
- Inbound email to your channel addresses keeps creating tickets and adding replies.
- The API keeps working: everything in this guide.
- SLA clocks keep running, and
sla.at_riskandsla.breachedstill fire. - Staff keep their notifications, internal notes and every screen they use.
- The customer portal and help centre stay open unless you switch them off. A headless organization that does not want customers to see DevStride's portal should close both.
Limits today#
- English only. The rendered
subject,textandhtmlare written in English. Write your own copy fromkindandmessageif you need another language. - Receipts for replies only. A delivery receipt needs a comment, so only
replymessages can take one. - "Powered by DevStride" stays on the portal. It is on every portal page. If that matters to you, close the portal.