Create a Webhook

5 minute read

With webhooks, you can subscribe to events that you find important, useful, or interesting.

To add a webhook via the API, form a request body according to our API Reference and issue a POST request to /NotificationWebHooks.

Important: To create and manage webhooks via the API, you need to have the following permissions:

  • For subscribers: an account with the Super Admin secondary role.
  • For providers: an account with the Provider Automation Admin access level.

We have also prepared several code examples based on your needs. Let’s create a webhook to get notifications of:

Important: Before registering webhooks, it is good to learn the difference between a webhook and subscription.

Create a Webhook With One Subscription

When you want to subscribe to events happening to one object, create a webhook that consists of one subscription.

Let’s set up a webhook to receive notifications each time someone creates or updates a work order.

  Subscription 1
Object WorkOrder
Events WorkOrderCreated, WorkOrderNoteAdded, WorkOrderStatusChanged

POST /NotificationWebHooks

Header Value
Content-Type application/json
Parameter Parameter type Example value
webhook Body See below

Example request:

POST https://sb2api.servicechannel.com/v3/NotificationWebHooks HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json

{
   "Subscriptions": [
      {
         "Name": "Subscription to WOs",
         "EventTypes": ["WorkOrderCreated", "WorkOrderNoteAdded", "WorkOrderStatusChanged"]
      }
   ],
   "Enabled": true,
   "Name": "Basic webhook",
   "Description": "I want to receive alerts when WOs are created or updated.",
   "Url": "https://yourCompany.com/webhook-target-URL"
}

Example response:

{
   "Id": 1
}

Response code: HTTP/1.1 201 Created

The response to this request contains the webhook ID.

Create a Webhook With Rules

After setting up the webhook described above, you will be getting alerts on all new and updated WOs. But if you need to subscribe to events that match certain criteria, it is time to use event filters that are also called event rules. You can filter events by category and trade.

Important: You cannot add rules for the FbInvitationAccepted event.

Let’s create a webhook to get alerts when invoices of the GLASS trade and CAPEX or MAINTENANCE categories are generated:

  Subscription 1
Object Invoice
Rules GLASS trade; CAPEX and MAINTENANCE categories
Events InvoiceCreated

POST /NotificationWebHooks

Header Value
Content-Type application/json
Parameter Parameter type Example value
webhook Body See below

Example request:

POST https://sb2api.servicechannel.com/v3/NotificationWebHooks HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json

{
   "Subscriptions": [
      {
         "Name": "Subscription to invoices",
         "EventTypes": ["InvoiceCreated"],
         "Rules": {
            "Trades": ["GLASS"],
            "Categories": ["CAPEX", "MAINTENANCE"]
         }
      }
   ],
   "Enabled": true,
   "Name": "Webhook with rules",
   "Description": "I want to receive alerts when invoices of the GLASS trade and CAPEX or MAINTENANCE categories are generated.",
   "Url": "https://yourCompany.com/webhook-target-URL"
}

Example response:

{
   "Id": 2
}

The response to this request contains the webhook ID.

Create a Webhook With Several Subscriptions

Different Objects

When you want to receive events related to different objects, set up a webhook that contains several subscriptions. Add one subscription per object.

Now we create a webhook that is built up of two subscriptions to receive events when someone creates or approves a proposal and when a provider accepts a subscriber’s invitation to Private Network.

  Subscription 1 Subscription 2
Object Proposal FbInvitation
Events ProposalCreated, ProposalApproved FbInvitationAccepted

POST /NotificationWebHooks

Header Value
Content-Type application/json
Parameter Parameter type Example value
webhook Body See below

Example request:

POST https://sb2api.servicechannel.com/v3/NotificationWebHooks HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json

{
   "Subscriptions": [
      {
         "Name": "Subscription to proposals",
         "EventTypes": ["ProposalCreated", "ProposalApproved"]
      },
      {
         "Name": "Subscription to FB invitation",
         "EventTypes": ["FbInvitationAccepted"]
      }
   ],
   "Enabled": true,
   "Name": "Multi-subscription webhook 1",
   "Description": "I want to receive alerts when proposals are created and approved as well as when providers accept my invitation to Private Network",
   "Url": "https://yourCompany.com/webhook-target-URL"
}

Example response:

{
   "Id": 3
}

Response code: HTTP/1.1 201 Created

The response to this request contains the webhook ID.

Different Filters

When you need to get events related to the same object, but want to apply different filters to different events, create a webhook with several subscriptions. Add one subscription per each set of rules.

Let’s create a webhook with two subscriptions for two different set of rules:

  Subscription 1 Subscription 2
Object Proposal Proposal
Rules CAPEX and MAINTENANCE categories GLASS and ROOF trades
Events ProposalRejected, ProposalVoided ProposalUserAssigned, ProposalWorkOrderAssigned

POST /NotificationWebHooks

Header Value
Content-Type application/json
Parameter Parameter type Example value
webhook Body See below

Example request:

POST https://sb2api.servicechannel.com/v3/NotificationWebHooks HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json

{
   "Subscriptions": [
      {
         "Name": "Subscription to canceled proposals",
         "EventTypes": ["ProposalRejected", "ProposalVoided"],
         "Rules": {
            "Categories": ["CAPEX", "MAINTENANCE"]
         }
      },
      {
         "Name": "Subscription to assigned proposals",
         "EventTypes": ["ProposalUserAssigned", "ProposalWorkOrderAssigned"],
         "Rules": {
            "Trades": ["GLASS", "ROOF"]
         }
      }
   ],
   "Enabled": true,
   "Name": "Multi-subscription webhook 2",
   "Description": "I want to receive alerts when some proposals are voided or rejected and some proposals are assigned to a user or a WO.",
   "Url": "https://yourCompany.com/webhook-target-URL"
}

Example response:

{
   "Id": 4
}

The response to this request contains the webhook ID.

Create a Webhook on All Events

When you want to be aware of everything that happens in ServiceChannel, issue this request to subscribe to all events that we support. Note that this webhook consists of five subscriptions as currently there are five event objects.

POST /NotificationWebHooks

Header Value
Content-Type application/json
Parameter Parameter type Example value
webhook Body See below

Example request:

POST https://sb2api.servicechannel.com/v3/NotificationWebHooks HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json

{
   "Subscriptions": [
      {
         "Name": "Subscription to WOs",
         "EventTypes": ["WorkOrderCreated", "WorkOrderNoteAdded", "WorkOrderStatusChanged"]
      },
      {
         "Name": "Subscription to check-in and -out",
         "EventTypes": ["WorkOrderCheckIn", "WorkOrderCheckOut"]
      },
      {
         "Name": "Subscription to invoices",
         "EventTypes": ["InvoiceCreated", "InvoiceOpen", "InvoiceApproved", "InvoiceOnHold", "InvoiceReviewed", "InvoiceRejected", "InvoicePaid", "InvoiceApprovalCodeChanged", "InvoiceVoided", "InvoiceDisputed", "InvoiceStarAdded", "InvoiceStarRemoved"]
      },
      {
         "Name": "Subscription to proposals",
         "EventTypes": ["ProposalCreated", "ProposalOpen", "ProposalApproved", "ProposalOnHold", "ProposalReviewed", "ProposalRejected", "ProposalUserAssigned", "ProposalWorkOrderAssigned", "ProposalVoided", "ProposalScheduled", "ProposalAttachmentAdded"]
      },
      {
         "Name": "Subscription to FB invitation",
         "EventTypes": ["FbInvitationAccepted"]
      }
   ],
   "Enabled": true,
   "Name": "All-event webhook",
   "Description": "I want to receive all ServiceChannel events.",
   "Url": "https://yourCompany.com/webhook-target-URL"
}

Example response:

{
   "Id": 5
}

Response code: HTTP/1.1 201 Created

The response to this request contains the all-event webhook ID.

Updated: