Guides

Webhooks Overview

Suggest Edits

SysAid Webhooks allow you to receive real-time notifications about events occurring in your environment. Instead of continuously polling our API, you can configure a webhook to be notified when key events happen. Webhook subscriptions are one of the easiest ways to integrate SysAid with your own apps, workflows, or monitoring tools, without polling or manual intervention.

What are Webhooks for?

Webhooks let you automate workflows and stay in sync with updates to your service records. When a specified event occurs in SysAid, we send an HTTP POST request to a URL you provide, with a payload containing event details.
Example use cases:

  • Triggering automations in third-party systems (e.g., Slack, Jira, custom tools)
  • Logging events externally
  • Synchronizing SysAid with external data sources

Supported events

You can subscribe to the following event types:

Event nameDescription
sr.createdTriggered when a new service record is created
sr.updatedTriggered when an existing service record is updated

📘

Please note:

When editing an existing service record in the Spaces interface, SysAid sends a webhook for each individual field change as the user makes it. These incremental webhooks do not include the sr_version.

Once the user finishes updating the service record and leaves the service record page, SysAid sends a final, comprehensive webhook. This "Full" webhook includes all the changes made during the session, along with the latest sr_version, providing a complete and consistent snapshot of the service record's updated state.

Webhook behavior and guarantees

BehaviorDetails
SLAEvents are typically sent within a few seconds and up to a couple of minutes
DeliveryBest-effort only. Delivery is not guaranteed. Your system should periodically reconcile the state using API calls.
Initial timeoutIf your server doesn’t respond within 10 seconds, it will count as a failure
RetriesAny HTTP 2xx response code stops retries
IdempotencyEach webhook includes a unique ID in the payload; this means your system should detect and ignore duplicates
Time formatWebhook payloads will contain timestamps in ISO 8601 format.

Best practices

  • Secure your endpoint: Validate the X-Sysaid-Signature and use HTTPS.
  • Implement retry logic: Treat webhook requests as non-deterministic and retry-safe.
  • Log and monitor: Keep track of webhook activity for auditing and debugging.

Creating a Webhook subscription

A webhook subscription is a configuration that tells SysAid: "Send data to this URL whenever specific events happen."

When you create a webhook subscription, you're registering:

  • The URL where you want to receive event notifications (your listener endpoint)
  • The events you want to be notified about (e.g., sr.created, sr.updated)
  • A description to help you identify it later

Once subscribed, SysAid will automatically send an HTTP POST request to your URL with a payload containing the service record ID whenever one of those events occurs.

To create a webhook subscription:

Send a POST request to:

https\://<your-subdomain>.sysaidit.com/connect/v1/webhooks

With a body like:

{  
  "url": "<https://your-listener.example.com/webhook-endpoint">,  
  "description": "your description",  
  "eventNames": ["sr.created", "sr.updated"]  
}

You will receive a payload like this:

{
  "eventName": "sr.created",
  "srId": 148,
  "updates": [
    {
      "fieldName": "assignedGroup",
      "currentValue": "none",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "autoPopulatedTicket",
      "currentValue": "false",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "richTextFields",
      "currentValue": "[RichTextFieldRequest(referencedEntityTableName=service_req, jsonContent={\"text\":\"<p>what</p>\",\"attachments\":[],\"inlineImages\":[]}, columnName=description)]",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "ticketTemplateId",
      "currentValue": "5",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "customColumnsFields",
      "currentValue": "{}",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "source",
      "currentValue": "1",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "duplicate",
      "currentValue": "false",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "type",
      "currentValue": "incident",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "title",
      "currentValue": "test 123",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "priority",
      "currentValue": "1",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "version",
      "currentValue": "1",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "secondaryCategory",
      "currentValue": "14",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "srType",
      "currentValue": "1",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "primaryCategory",
      "currentValue": "4",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "urgency",
      "currentValue": "1",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "requestUser",
      "currentValue": "admautoqa",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "coreUpdate",
      "currentValue": "false",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "assignee",
      "currentValue": "adm",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "status",
      "currentValue": "1",
      "previousValue": "",
      "timestamp": 1751280965889
    },
    {
      "fieldName": "thirdLevelCategory",
      "currentValue": "20",
      "previousValue": "",
      "timestamp": 1751280965889
    }
  ]
}

Now, every time a service record is created or updated, your server will get a POST request from SysAid with the details.

X-Sysaid-Signature Header

Every webhook request includes a signature in the X-Sysaid-Signature header. You can use this to verify the authenticity of incoming requests and ensure they originated from SysAid.

We recommend validating this signature in your listener logic.

Next steps

To create a subscription and explore all Webhook related API endpoints, go to the Webhooks API Reference.

Updated 12 days ago