Skip to main content

​
About Freshservice

Freshservice is a IT-service-management platform. Connecting Freshservice to Serval allows the syncing of tickets between the two systems.

​
What the Freshservice integration enables

CapabilityDescription
Access ManagementCreate, update, and manage users and their permissions
Automation workflowsTrigger automated processes and approval flows
Sync TicketsMaintain data consistency across platforms, sync tickets between Serval and Freshservice

​
Freshservice configuration (in Freshservice)

You authenticate Serval with a Freshservice API key tied to an agent account. The agent account determines what Serval can do via the Freshservice API, so proper setup is critical for ticket syncing to work.
Serval needs agent-level access to create tickets, update tickets, and post replies. A requester-only account will result in 403 Forbidden errors during ticket syncing. The account must be an Agent, not a Requester.
1

Create a new agent

Navigate to Admin → click the hamburger menu in the top left → Global Settings → “Agents” in the User Management section.Click New Agent and fill in the details:
  • Name: Serval Integration (or any descriptive name)
  • Email: A valid email address (e.g., serval-integration@yourcompany.com)
  • Agent Type: Make sure this is Full-time Agent, not Occasional Agent
The agent must be a Full-time Agent. Occasional Agents have restricted API access and cannot perform all the operations Serval needs (creating tickets, posting replies, updating fields).
2

Configure account-wide permissions

After creating the agent, go to the agent’s profile → Permissions → “Add admin role” under account-wide permissions.Select Workspace Admin → Save.This grants the agent admin-level API access across all workspaces.
3

Create a custom workspace role

Create a dedicated role in Freshservice before assigning workspace access:
  1. Go to Admin → click the hamburger menu in the top left → Global Settings → Roles.
  2. Click New role.
  3. Name the role Serval Supervisor.
  4. Under Tickets, configure at least these minimum permissions:
    • View tickets
    • Send reply to a ticket
    • Forward a conversation
    • Edit notes → Edit everyone’s notes
    • Delete a conversation
    • Merge / split a ticket
    • Edit ticket properties
    • Move tickets
    • Create and Edit Tasks in Tickets → Allow reordering of tasks
    • Delete a ticket
    • Export Tickets
  5. Click Save.
You can grant additional permissions if your process requires them, but the list above is the minimum needed for Serval ticket sync.
4

Assign workspace permissions to the service account

Under the service account’s Workspace permissions, click Add to workspace → Add role.Select “Serval Supervisor” and “across the workspace” → Save.
  • Repeat this step for every workspace that you want Serval to sync tickets with. Without workspace-level permissions, Serval will receive 403 Forbidden errors when trying to create or update tickets in that workspace.
  • For any group where you assign this role, if the group is restricted, also add the service account to that group itself.
5

Activate the agent and enable API access

  1. Ensure the agent account is activated — the agent must accept the invitation email and set a password.
  2. Sign in as the agent → go to Profile Settings (top-right avatar) → API Settings.
  3. Ensure the API key is enabled. Copy the API key.
If the agent has never signed in, the API key will not work. The agent must complete the activation process first.

​
Using an existing admin account

If you prefer not to create a dedicated service account, you can use an existing admin’s API key. Sign in as the admin → go to Profile Settings → API Settings and copy the key.
When using an admin’s API key, all ticket actions performed by Serval (creating tickets, posting replies) will appear as if that admin performed them in Freshservice.

​
Serval Configuration

  1. In Serval navigate to Apps → Available → Freshservice → Connect.
  2. Complete the form:
Freshservice Connection Form
FieldValue
Service Instance IDYour Freshservice domain. For https://acme.freshservice.com enter acme.freshservice.com.
API KeyThe key you generated above.
  1. Click Save.
Serval can now post comments, update tickets and read data according to the Freshservice permissions you configured.

​
Real-time Ticket Synchronization with Webhooks (Optional)

By default, Serval polls Freshservice every 30 seconds to sync tickets. For faster, real-time synchronization, you can configure Freshservice webhooks to push updates to Serval immediately.
Webhook setup is optional. Polling will continue to work as a fallback even after webhooks are configured.

​
Benefits of webhooks

  • Lower latency: Ticket changes appear in Serval within seconds instead of up to 30 seconds
  • Reduced API usage: Fewer outbound API calls from Serval to Freshservice
  • Better rate limit management: Less likely to hit Freshservice API limits for high-volume environments

​
Prerequisites

Before configuring webhooks, ensure you have:
  • Admin access to Freshservice
  • A working Serval integration (completed the steps above)
  • Your Serval webhook URLs and authentication token (found in Serval’s ticket sync settings page for your Freshservice integration)

​
Find your webhook URLs and token in Serval

In Serval, navigate to your Freshservice integration’s ticket sync settings. You will see two webhook URLs and an authentication token:
FieldPurpose
Ticket Update Webhook URLEnds with /ticket-update — use this for the Ticket Update automator
New Reply Webhook URLEnds with /reply — use this for the New Message automator
Authentication TokenSame token used for both webhooks
Serval webhook configuration panel showing two webhook URLs, authentication header name, and authentication token

​
Overview

Serval uses two separate webhooks for Freshservice — one for ticket updates and one for new messages. This separation ensures that ticket metadata and messages are processed independently, which improves reliability and avoids duplicate message ingestion.
WebhookTriggerURL suffixPurpose
Ticket UpdateTicket is Updated/ticket-updateSyncs ticket field changes (status, priority, assignment, etc.)
New MessageReply is sent/replySyncs new messages (replies and forwards)
You will create two Workflow Automators in Freshservice — one for each webhook.

​
Webhook 1: Ticket Updates

This webhook fires when ticket fields change (status, priority, assignee, etc.). It does not include message data.
1

Navigate to Workflow Automator

In Freshservice, go to Admin → Helpdesk Productivity → Workflow Automator.Click New Automator to create a new workflow.
2

Create the automator

Configure the automator with a Ticket is Updated event that triggers a Trigger Webhook action:
SettingValue
NameServal - Ticket Update Webhook
EventTicket is Updated
3

Configure the webhook action

Under Actions, add a Trigger Webhook action with the following settings:
FieldValue
Request TypePOST
Callback URLCopy and paste the Ticket Update Webhook URL from Serval’s ticket sync settings
EncodingJSON
AuthenticationSelect No Auth
Custom HeadersX-Serval-Webhook-Token set to the authentication token from Serval
Make sure the Callback URL ends with /ticket-update. Without this suffix the webhook will be rejected.
In the Content section of the webhook action, select the following properties. These are the ticket fields Serval uses for syncing:
  • Ticket ID
  • Ticket ID
  • Subject
  • Description
  • Ticket URL
  • Status
  • Priority
  • Type
  • Source
  • Urgency
  • Impact
  • Category
  • Group Name
  • Agent Name
  • Agent Email
  • Department Name
  • Tags
  • Created At
  • Due By Time
  • Current Date and Time
  • Helpdesk Name
  • Helpdesk URL
  • Event Performer ID
  • Event Performer Name
  • Event Performer Email
Do not select Latest Public Comment. Message data should only be sent via the New Message webhook (below).
Save the automator.
4

Enable the automator

Ensure the automator is Active. You can toggle it on from the Workflow Automator list.
Test by changing a ticket’s status or priority in Freshservice. The change should appear in Serval within seconds.

​
Webhook 2: New Messages

This webhook fires when a new message (reply or forward) is sent on a ticket. It includes message metadata so Serval can correlate the message to the correct ticket.
1

Create a new automator

In Freshservice, go to Admin → Helpdesk Productivity → Workflow Automator.Click New Automator to create a second workflow.
2

Configure the automator

SettingValue
NameServal - New Message Webhook
EventReply is sent
3

Configure the webhook action

Under Actions, add a Trigger Webhook action:
FieldValue
Request TypePOST
Callback URLCopy and paste the New Reply Webhook URL from Serval’s ticket sync settings
EncodingJSON
AuthenticationSelect No Auth
Custom HeadersX-Serval-Webhook-Token set to the authentication token from Serval
Make sure the Callback URL ends with /reply. Without this suffix the webhook will be rejected.
In the Content section, select only the properties needed to identify the ticket and the message:
  • Ticket ID
  • Ticket ID
  • Latest Public Comment
  • Helpdesk URL
  • Current Date and Time
  • Event Performer ID
  • Event Performer Name
  • Event Performer Email
You don’t need to select ticket metadata fields (status, priority, etc.) here. Those are handled by the Ticket Update webhook.
Save the automator.
4

Enable the automator

Ensure the automator is Active.
Test by replying to a ticket in Freshservice. The message should appear in Serval within seconds.

​
Enabling webhooks in Serval

After creating both Workflow Automators in Freshservice, return to Serval’s ticket sync settings and toggle on Enable webhook sync. This tells Serval to expect webhooks for real-time updates.
Enabling webhook sync disables polling. Make sure both Workflow Automators are active before enabling this setting.

​
Troubleshooting webhooks

  • Verify that both webhook URLs are correct and include the proper suffix (/ticket-update or /reply)
  • Check that the Serval integration is properly configured and connected
  • Ensure both Workflow Automators are active in Freshservice
  • Confirm the X-Serval-Webhook-Token header value matches what Serval shows
  • Make sure you created the second automator with the Reply is sent event (not Ticket is Updated)
  • Verify the Callback URL ends with /reply
  • Check that Latest Public Comment is selected in the New Message webhook’s Content properties
If webhooks appear to be working but updates are delayed:
  • Freshservice may be batching webhook deliveries during high load
  • Check Freshservice’s webhook delivery logs for failures
  • Polling will continue to work as a fallback
If Serval can read tickets from Freshservice but fails when creating, updating, or replying to tickets:
  1. Verify the agent type — The API key must belong to a Full-time Agent, not a Requester or Occasional Agent. Navigate to Admin → Agents and check the agent’s type.
  2. Check workspace access — The agent must have an explicit role in each workspace where Serval syncs tickets. Go to the agent’s profile → Workspace permissions and confirm the agent has Serval Supervisor (or an equivalent custom role with the same minimum permissions) for the relevant workspaces.
  3. Check restricted group membership — For any group where you assign this role, if the group is restricted, add the service account to that group itself.
  4. Verify agent activation — The agent must have completed the activation process (accepted invitation email, set a password). An unactivated agent’s API key will not have full access.
  5. Check API key status — Sign in as the agent → Profile Settings → API Settings and ensure the API key is enabled.
  6. Test the API key directly — Run this command to verify the agent’s access: 
curl -u "YOUR_API_KEY:X" "https://your-domain.freshservice.com/api/v2/tickets?per_page=1"
If this returns a 403, the API key does not have sufficient permissions.