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
| Parameter | Explanation |
|---|---|
| WebHookUri | The 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." |
| Secret | A 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. |
| 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
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
[
{
"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.