REST API endpoint of WebHooks Service

Interaction with the Trados GroupShare WebHooks Service happens through REST API calls, secured with bearer tokens (that you get using Trados GroupShare 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 Trados GroupShare WebHooks.

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

Register a web hook with Trados GroupShare.

Request information

ParameterExplanation
WebHookUriThe URI used by Trados 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 Trados GroupShare will do endpoint verification to check that the supplied endpoint exists i.e. upon receiving the web hook registration request Trados 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 Trados 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."
SecretA shared secret, created as part of subscribing to events. The receiver uses this shared secret to validate that the request comes from Trados GroupShare. The WebHook secret key parameter must be between 32 and 64 characters long.
FiltersArray 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

GET api/webhooks/registrations/admin/all

Returns all Webhooks registered with the system. It requires 'Manage WebHooks Registrations' permission.

Request information

URI parameters: none.

Body parameters: none.

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

Response information

HTTP response: 200 OK and a JSON array of all the Webhook registrations.
[
    {
        "Headers": {},
        "Properties": {},
        "Filters": [
            "Sdl.GroupShare.Events.V2.AssignmentEvent"
        ],
        "UserName": "username who registered the event",
        "Id": "webhook registration id",
        "WebHookUri": "callback URL",
        "Secret": "12345678901234567890123456789012",
        "Description": "description",
        "IsPaused": false
    }
]     

DELETE api/webhooks/registrations/admin/delete

Deletes one or more Webhook registrations, identified by the list of Webhook id passed in. It requires 'Manage WebHooks Registrations' permission.

Request information

URI parameters: WebHook registration id.

Body parameters: none.

DELETE /api/webhooks/registrations/admin/delete?registrationIds={list of registrationIds, separated by comma} HTTP/1.1
Host: localhost:41239
Authorization: Bearer token
Response information

HTTP response: 200 OK or 404 Not Found.