GroupShare WebHooks Service

WebHooks provide a publish / subscribe model for wiring together Web APIs and services. You can subcribe to GroupShare events and get notified when that event happens, through a callback.

When subscribing to an event you need to provide a callback URI where you want to be notified when the event occurs. When the event occurs an HTTP POST request is sent to your callback URI with information about what happened.

GroupShare WebHooks Service

GroupShare WebHooks Service is implemented as a standalone self hosted Rest API application, that can be run as a Windows Service or in console mode (using --console switch).
The default port that the Rest API self hosted service listens is 41239.

Configuration

Configuration for the WebHooks service is done in Sdl.GroupShare.WebHooksService.exe.config under C:\Program Files\SDL\SDL Server\WebHooks Service (only relevant settings are shown):

<appSettings>
  <add key="RestHostUrl" value="http://+:41239" />
  <add key="MessageQueueHost" value="localhost" />
  <add key="MessageQueueUserName" value="gssvc" />
  <add key="MessageQueueUserPassword" value="u5F/lWdnD+snwvYcjKv/Fg==" />
  <add key="WebHookQueueName" value="GsWebHookQueue" />
  <add key="WebHookQueueDeadLetterName" value="GsWebHookQueueDeadLetter" />
  <add key="WebHookQueueDLXName" value="GsWebHookDlx" />
  <add key="Server" value="gs-test-url.sdltest.com" />
  <add key="serilog:write-to:RollingFile.pathFormat" value="C:\ProgramData\SDL\Service\logs\WebHooks.Log" />
</appSettings>
<connectionStrings>
  <add name="MS_SqlStoreConnectionString" connectionString="Server=(local)\sqlserver2014;Database=SDLSystem;Trusted_Connection=True;" providerName="System.Data.SqlClient" />
</connectionStrings>

Above you can see the configuration used for the service listening port, the RabbitMQ message queue and the database where the web hook registrations will be stored.

RestHostUrl

The host and port setting that the Web Hooks Service will use to listen on.

MessageQueueHost, MessageQueueUserName, MessageQueuePassword

These are configured by GroupShare installer and are needed to consume messages from RabbitMQ.

WebHookQueueName, WebHookQueueDeadLetterName, WebHookQueueDLXName

Used to specify the queues to consume messages from. It would be possible to create new queues with different routing keys. Recommended to leave as it is.

Server

The value of the Server setting will be included in the callback request body, to know the web hook sender of the message. See the "Server" property in each message body.

Supported Filters

You can subscribe to all existing events by using the "*" filter and a single callback handling URL.
The available filter types are as follows:

Sdl.GroupShare.Events.V2.ProjectCreatedEvent
Sdl.GroupShare.Events.V2.PhaseChangeEvent
Sdl.GroupShare.Events.V2.AssignmentEvent
Sdl.GroupShare.Events.V2.CheckOutEvent
Sdl.GroupShare.Events.V2.CheckInEvent
*

Rest API endpoint of WebHooks Service

Interaction with the GroupShare WebHooks Service happens through Rest API calls, secured with bearer tokens (that you get using GS Management Rest API login endpoint).

GET api/webhooks/filters

Returns all WebHooks filters that a user can register with. Basically, these are the events that you'll get notification of when it happens.

Request information

URI parameters: none.
Body parameters: none.

GET /api/webhooks/filters HTTP/1.1
Host: localhost:41239
Authorization: Bearer token

Response information

A JSON array of the existing filters.

HTTP response: 200 OK

[
    {
        "Name": "Sdl.GroupShare.Events.V2.ProjectCreatedEvent",
        "Description": "A project has been created"
    },
    {
        "Name": "Sdl.GroupShare.Events.V2.PhaseChangeEvent",
        "Description": "A files phase has been changed"
    },
    {
        "Name": "Sdl.GroupShare.Events.V2.AssignmentEvent",
        "Description": "An assignment has been changed"
    },
    {
        "Name": "Sdl.GroupShare.Events.V2.CheckOutEvent",
        "Description": "A file has been checked out"
    },
    {
        "Name": "Sdl.GroupShare.Events.V2.CheckInEvent",
        "Description": "A file has been checked in"
    },
    {
        "Name": "*",
        "Description": "Listen in on all events."
    }
]

GET /api/webhooks/registrations

Returns all existing registrations to GS WebHooks.

Request information

URI parameters: none.
Body parameters: none.

GET /api/webhooks/registrations HTTP/1.1
Host: localhost:41239
Authorization: Bearer token

Response information

HTTP response: 200 OK

[
    {
        "Id": "1e41d718057743c5ab91492a7d23ea19",
        "WebHookUri": "http://localhost:41240/api/phasechange?noecho",
        "Secret": "GroupShareRocks",
        "Description": "PhaseChange callback endpoint",
        "IsPaused": false,
        "Filters": [
            "Sdl.GroupShare.Events.V2.PhaseChangeEvent"
        ],
        "Headers": {},
        "Properties": {}
    },
    {
        "Id": "6614a59a71434511b399a9a3eb8bda7c",
        "WebHookUri": "http://localhost:41240/api/callbacks?noecho",
        "Secret": "GroupShareRocks",
        "Description": "Subscription to all filters",
        "IsPaused": false,
        "Filters": [
            "*"
        ],
        "Headers": {},
        "Properties": {}
    }
]

POST /api/webhooks/registrations

Request information

Parameter	Explanation
WebHookUri	The URI used by GroupShare to do a POST request when the event occurs, that you subscribed to using the filter. WebHookUri query string parameters Use the 'noecho' parameter to register a web hook without endpoint verification. If you don't supply this parameter GroupShare will do endpoint verification to check that the supplied endpoint exists i.e. upon receiving the web hook registration request GroupShare will do a GET request to the WebHookUri. If this is desired then you need to send also an echo query string parameter and when receiving the verification request you need to return the exact content of that parameter in plain text. Otherwise GroupShare will reject webhook registration with a message: "WebHook verification failed. Please ensure that the WebHook URI is valid and that the endpoint is accessible."
Secret	A shared secret, created as part of subscribing to events. The receiver uses this shared secret to validate that the request comes from GroupShare. The WebHook secret key parameter must be between 32 and 64 characters long.
Filters	Array of filters that you are interested in subscribing. You can subscribe to multiple events at once, in this case your callback needs to know how to handle the different callback data. Or subscribe to events one by one with different callback endpoints.

POST /api/webhooks/registrations HTTP/1.1
Host: localhost:41239
Authorization: Bearer token
Content-Type: application/json
{
    WebHookUri: "http://localhost:41240/api/phasechange?noecho",
    Secret: "GroupShareRocks",
    Description: "PhaseChange callback endpoint",
    Filters: ["Sdl.GroupShare.Events.V2.PhaseChangeEvent"]
}

Response information

HTTP response: 201 Created

{
    "Id": "1e41d718057743c5ab91492a7d23ea19",
    "WebHookUri": "http://localhost:41240/api/phasechange?noecho",
    "Secret": "GroupShareRocks",
    "Description": "PhaseChange callback endpoint",
    "IsPaused": false,
    "Filters": [
        "Sdl.GroupShare.Events.V2.PhaseChangeEvent"
    ],
    "Headers": {},
    "Properties": {}
}

DELETE /api/webhooks/registrations

Delete a web hook registration.

Request information

URI parameters: WebHook registration id. If no registration id is supplied in the URI all registrations will be deleted.
Body parameters: none.

DELETE /api/webhooks/registrations/{registration id} HTTP/1.1
Host: localhost:41239
Authorization: Bearer

Response information

HTTP response: 200 OK or 404 Not Found

Receiving WebHooks Notifications (callbacks)

After a WebHook URI was registered for a certain event you will get callbacks when that event occurs. The callback is a POST request.

Request headers

Parameter	Explanation
ms-signature	An SHA 256 signature on the request body. The signature uses the secret key from the WebHook registration. Example: "sha256=275F1BFF2327BBAF7F61A1BB1920BAC0A5295C2F4C78312345247031D37A8031"
X-Correlation-ID	A correlation guid - this is the actual id of a webhook item (from GroupShare)

Request body

Body type

Explanation

JSON (application/json)

The event details as a JSON string.

Example request body of an assignment event callback:

{                                                             
  "Id": "9745600de970448b97f1cff97dbf1860",                   
  "Attempt": 1,                                               
  "Properties": {},                                           
  "Notifications": [                                          
    {                                                         
      "Action": "Sdl.GroupShare.Events.V2.AssignmentEvent",   
      "From": [                                               
        {                                                     
          "userEmail": "projman@testsdl.com"                      
        }                                                     
      ],                                                      
      "To": [                                                 
        {                                                     
          "userEmail": "translator@testsdl.com"                   
        }                                                     
      ],                                                      
      "LanguageFileId": "1c210645-8b48-4557-b6e3-d50d1ca18ab4",
      "ProjectId": "6ed3763d-0a93-4484-89e3-c9b4b824701d",    
      "RaisedBy": "test",                                     
      "Server": "groupshare.local"                            
    }                                                         
  ]                                                           
}

Postman collection

see GS WebHooks.postman_collection.json

Other informations related to GroupShare WebHooks

Receiver and Sending flows

WebHook Receiver Registration Flow

Registration Request Structure

{
  "WebHookUri":"http://<hosturl>/api/webhooks/incoming/custom",
  "Secret":"12345678901234567890123456789033",
  "Description":"Sample WebHook Reciever.",
  "Filters":[ "Sdl.GroupShare.Events.V2.ProjectCreatedEvent",
              "Sdl.GroupShare.Events.V2.PhaseChangeEvent",
              "Sdl.GroupShare.Events.V2.AssignmentEvent",
              "Sdl.GroupShare.Events.V2.CheckInEvent",
              "Sdl.GroupShare.Events.V2.CheckoutEvent"
            ]
}

Sending WebHook Messages Flow

Event Message Design

Project Created Event

Headers
Key	Value
X-Correlation-ID	Correlation ID
Message Body
Property Name	Value
ProjectId	Project ID
ProjectName	Project name
RaisedBy	Username of the user who triggered the event.
Server	GroupShare server name, read from WebHookService settings.
Action	Sdl.GroupShare.Events.V2.ProjectCreatedEvent

{
      "Action": "Sdl.GroupShare.Events.V2.ProjectCreatedEvent",
      "ProjectName": "0430 - 1311",
      "ProjectId": "3b7755a7-9ad3-4541-824e-81f8accadbaa",
      "RaisedBy": "sa",
      "Server": "groupshare.local"
}

Phase Change Event

Headers
Key	Value
X-Correlation-ID	Correlation ID
Message Body
Property Name	Value
ProjectId	Project ID
LanguageFileId	File ID
Phase	JSON object that contains "id" and "name" members for phase id and phase name.
RaisedBy	Email address of the user who triggered the event
Server	GroupShare server name, read from WebHookService settings.
Action	Sdl.GroupShare.Events.V2.PhaseChangeEvent

Example Message Body

{
  "Action": "Sdl.GroupShare.Events.V2.PhaseChangeEvent",
  "Phase": {
    "id": 22,
    "name": "Translation"
  },
  "LanguageFileId": "ce88d061-284c-4af6-9902-62c1b9e5decf",
  "ProjectId": "2a299c68-20c0-4bd3-87d0-a0d8c1490cf4",
  "RaisedBy": "sa",
  "Server": "groupshare.local"
}

Assignment Change Event

Headers
Key	Value
X-Correlation-ID	Correlation ID
Message Body
Property Name	Value
ProjectId	Project ID
LanguageFileId	File ID
From	Collection of users who were assigned before the assignment change.
To	Collection of user who are now assigned.
RaisedBy	Email address of the user who triggered the event
Server	GroupShare server name, read from WebHookService settings.
Action	Sdl.GroupShare.Events.V2.AssignmentEvent

Example Message Body

{
  "Action": "Sdl.GroupShare.Events.V2.AssignmentEvent",
  "From": [
    {
      "userEmail": "sa"
    }
  ],
  "To": [
    {
      "userEmail": "pm"
    },
    {
      "userEmail": "sa"
    }
  ],
  "LanguageFileId": "ce88d061-284c-4af6-9902-62c1b9e5decf",
  "ProjectId": "2a299c68-20c0-4bd3-87d0-a0d8c1490cf4",
  "RaisedBy": "sa",
  "Server": "groupshare.local"
}

Check Out Change Event

Headers
Key	Value
X-Correlation-ID	Correlation ID
Message Body
Property Name	Value
ProjectId	Project ID
LanguageFileId	File ID
RaisedBy	Email address of the user who triggered the event
Server	GroupShare server name, read from WebHookService settings.
Action	Sdl.GroupShare.Events.V2.CheckOutEvent

Example Message Body

{
  "Action": "Sdl.GroupShare.Events.V2.CheckOutEvent",
  "LanguageFileId": "ce88d061-284c-4af6-9902-62c1b9e5decf",
  "ProjectId": "2a299c68-20c0-4bd3-87d0-a0d8c1490cf4",
  "RaisedBy": "sa",
  "Server": "groupshare.local"
}

Check In Change Event

Headers
Key	Value
X-Correlation-ID	Correlation ID
Message Body
Property Name	Value
ProjectId	Project ID
LanguageFileId	File ID
RaisedBy	Email address of the user who triggered the event
Server	GroupShare server name, read from WebHookService settings.
Action	Sdl.GroupShare.Events.V2.CheckInEvent

Example Message Body

{
   "Action": "Sdl.GroupShare.Events.V2.CheckInEvent",
   "LanguageFileId": "ce88d061-284c-4af6-9902-62c1b9e5decf",
   "ProjectId": "2a299c68-20c0-4bd3-87d0-a0d8c1490cf4",
   "RaisedBy": "sa",
   "Server": "groupshare.local"
 }

Recommended

GroupShare Developers > GroupShare API

GroupShare WebHooks Service

GroupShare WebHooks Service

Configuration

RestHostUrl

MessageQueueHost, MessageQueueUserName, MessageQueuePassword

WebHookQueueName, WebHookQueueDeadLetterName, WebHookQueueDLXName

Server

Supported Filters

Rest API endpoint of WebHooks Service

GET api/webhooks/filters

GET /api/webhooks/registrations

HTTP response: 200 OK

POST /api/webhooks/registrations

DELETE /api/webhooks/registrations

Receiving WebHooks Notifications (callbacks)

Postman collection

Other informations related to GroupShare WebHooks

Receiver and Sending flows

Sending WebHook Messages Flow

Project Created Event

Phase Change Event

Assignment Change Event

Check Out Change Event

Check In Change Event