Manage Webhooks

4 minute read

After setting up webhooks, you will be receiving real-time notifications and will not need to poll for new data anymore. However, sometimes you may need to re-configure your webhooks.

Update a Webhook

Using the API, you can edit a webhook name or URL, update subscriptions, apply new rules, and even add more subscriptions to a webhook.

Get a Webhook

To update a webhook, you will sometimes need to pass all webhook data and also know the IDs of the subscriptions stored within the webhook.

Send this GET request to obtain this information:

GET /NotificationWebHooks/{webhookId}

Parameter Parameter type Example value
webhookId Path 1

Example request:

GET https://sb2api.servicechannel.com/v3/NotificationWebHooks/1 HTTP/1.1
Authorization: Bearer {access_token}

Example response:

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

Response code: HTTP/1.1 200 OK

The response to this request contains all webhook data.

Update a Webhook Name, URL, or Description

To update a webhook name or URL, pass the Name and Url parameters. To update a webhook description, you need to pass Name, Url, and Description.

Let’s see how to update the webhook target URL.

PUT /NotificationWebHooks/{webhookId}

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

Example request:

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

{
   "Name": "All-event webhook",
   "Url": "https://yourCompany.com/webhook-target-URL-new"
}

Response code: HTTP/1.1 204 No Content

Add a Subscription

To add a subscription, you need to pass both the current webhook data and new subscription data.

Let’s add a subscription to the webhook we have previously retrieved. The second subscription in the request body, called Subscription to invoices is a subscription that we are adding.

PUT /NotificationWebHooks/{webhookId}

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

Example request:

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

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

Response code: HTTP/1.1 204 No Content

To update a subscription, you need to pass both the current webhook data and the updated subscription data.

Retrieve the webhook to which we have just added a subscription, copy the webhook data, and update the data of the required subscription. We are adding rules to the second subscription.

PUT /NotificationWebHooks/{webhookId}

Header Value
Content-Type application/json
Parameter Parameter type Example value
id Path 1
request Body See below

Example request:

PUT https://sb2api.servicechannel.com/v3/NotificationWebHooks/1 HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json
{
   "Subscriptions": [
      {
         "Id": 1178,
         "Name": "Subscription to WOs",
         "EventTypes": ["WorkOrderCreated", "WorkOrderNoteAdded"],
         "Rules": {
            "Trades": [],
            "Categories": []
         }
      },
      {
         "Id": 1182,
         "Name": "Subscription to invoices",
         "EventTypes": ["InvoicePaid"],
         "Rules": {
            "Trades": ["GLASS"],
            "Categories": ["CAPEX", "MAINTENANCE"]
         }
      }
   ],
   "Id": 1,
   "Enabled": true,
   "Name": "Basic webhook",
   "Description": "I want to receive alerts when WOs are created or updated.",
   "Url": "https://yourCompany.com/webhook-target-URL"
}

Response code: HTTP/1.1 204 No Content

Delete a Subscription

To delete a subscription, you need to know its ID. Retrieve the webhook to get the ID of the subscription you want to erase.

We will delete the subscription that we have just updated.

DELETE /NotificationSubscriptions/Http/{id}

Parameter Parameter type Example value
id Path 1182

Example request:

DELETE https://sb2api.servicechannel.com/v3/NotificationSubscriptions/Http/1182 HTTP/1.1
Authorization: Bearer {access_token}

Response code: HTTP/1.1 204 No Content

Enable or Disable a Webhook

Sometimes you may need to temporarily deactivate a webhook or enable an inactive webhook.

To activate or deactivate a webhook, you need to pass Name, Url, and Enabled parameters.

PUT /NotificationWebHooks/{webhookId}

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

Example request to disable a webhook:

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

{
   "Name": "All-event webhook",
   "Url": "https://yourCompany.com/webhook-target-URL-new",
   "Enabled": false
}

Note: When you disable a webhook, it is not deleted from our system, so you can re-enable it at any time.

Example request to enable a webhook:

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

{
   "Name": "All-event webhook",
   "Url": "https://yourCompany.com/webhook-target-URL-new",
   "Enabled": true
}

Response code: HTTP/1.1 204 No Content

Delete a Webhook

When you are 100% sure that you do not need a particular webhook anymore, erase it from the ServiceChannel system.

Send the following request to delete a webhook:

DELETE /NotificationWebHooks/{webhookId}

Parameter Parameter type Example value
webhookId Path 5

Example request:

DELETE https://sb2api.servicechannel.com/v3/NotificationWebHooks/5 HTTP/1.1
Authorization: Bearer {access_token}

Response code: HTTP/1.1 204 No Content

Updated: