- Authors
- Contact
Michael JasonSmith <mpj17@onlinegroups.net>
- Date
2015-06-19
- Organization
- Copyright
This document is licensed under a Creative Commons Attribution-Share Alike 4.0 International License by OnlineGroups.net.
console
GroupServer provides web hooks that allow external programs to access some features. All the hooks work the same way:
- Data, including a token for authentication, is sent to a form as an HTTP
POST
, - The system processes the request, and
- The response is returned as a JSON object.
GroupServer uses some of these hooks itself — for tasks such as for adding email (see postfix-configure
) and sending out regular notifications (see cron
).
Here I first discuss the authentication token. I then introduce the hooks that are provided to allow external systems to retrieve group information and manage the profile life-cycle: creating, retrieving, and removing profiles.
Feel free ask any questions regarding the hooks in GroupServer Development group.
Note
The URLs used for web hooks are often quite long. This is deliberate, as it makes them easy to spot, and easier to understand as they refer to the GroupServer subsystem that provides the functionality.
All the web-hooks require the token
parameter to be sent when an HTTP POST
is made to the hook. The value of this token is written down in the etc/gsconfig.ini
file, as the token
parameter for the webservice
section of the configuration.
A unique token is created when you install GroupServer. It is very important that you keep this token secret. If the token accessed by a nefarious individual then they can do extensive harm your site.
However, all is not lost if the token is exposed, as you can generate a new token.
Warning
Because consequence of the token being divulged is so high it is recommended that the hooks are only used from the same machine as GroupServer (so it never travels over a network), or using secure connections (TLS).
Generate a new token if the token used to authenticate the web hooks is exposed.
- Run the
gs_auth_token_create
program, in thebin
directory of your GroupServer install.- It takes a data-source name (DSN) as its only argument, identifying the PostgreSQL database to connect to.
- The DSN for your GroupServer site is listed as the
dsn
parameter for thedatabase
section of the configuration in theetc/gsconfig.ini
file.
The
gs_auth_token_create
program will- Generate a new token,
- Change the value of the token in the PostgreSQL database, and
- Report the value of the token.
At this point the token in the PostgreSQL database and the
etc/gsconfig.ini
file will be different, so all web hooks will be broken. This includes the hook that used by thesmtp2gs
program, which adds email messages to the site.- Edit the
etc/gsconfig.ini
file and change thetoken
parameter in thewebservice
section. Save the file. All web hooks will be running again. No restart of GroupServer is necessary to change the token.
The documentation at Read the Docs contains more details about the gs_auth_token_create
program.
The web hook /gs-group-groups.json
is the simplest web-hook. It takes the authentication token (token
) and the action (get
) — and it returns a list of group-objects.
The documentation for the Groups web-hook has more details about how the hook works, including examples.
There are web-hooks for managing the entire life-cycle of a profile.
- Create a profile when you add a profile to a group for the first time,
- Find more about people when you retrieve profile information.
- Finally, you can remove a profile from a group (or site).
Most of the profile-related web hooks return the same profile data.
The profile data returned by the hooks involved in the profile life-cycle all return the same properties for the profiles, either as a single JSON object, as part of a list, or as a property of another object.
In the example JSON object below is the profile for someone called A Person
. The have set a nickname, so the URL to the profile does not contain their profile-identifier. They have two email addresses — with their home address preferred, and no unverified addresses. Finally, the person belongs to two groups: Example, and Test.
{ "id": "qK7SgjsTHcLNrJ2ClevcJ0", "name": "A Person", "url": "https://groups.example.com/p/aperson", "email": { "all": [ "a.person@home.example.com", "a.person@work.example.com" ], "preferred": [ "a.person@home.example.com" ], "other": [ "a.person@work.example.com" ], "unverified": [] }, "groups": [ "example", "test" ] }
The web-hook /gs-group-member-add.json
is used to add a profile to a group. It will also create a profile, if one does not exist for that person already. The hook takes
- The authentication token (
token
), - A name (
fn
), - an email address (
email
), - A group identifier (
groupId
), and - An action (
add
).
It returns the profile data of the person that has been added to the group, as well as some details about whether a profile was created, or already existed.
The documentation for the Add a profile web-hook has more details about how the hook works, including examples.
There are three ways to retrieve profile information: information about an individual, and information about people that belong to a site.
The web-hook /gs-search-people.json
allows you to retrieve information about an individual, using their user-identifier or email address. The hook takes
- An authentication token,
- The identifying information about someone (
user
) — which is either the user-identifier or email address), and - An action (
search
).
It returns the profile data of the person, or an empty object ({}
) if no one could be found.
The documentation for the Search for people web-hook has more details about how the hook works, including examples.
The web-hook /gs-site-member.json
allows you to retrieve information about the site members in a couple of ways.
- If passed an authentication token and an action of
users
then a simple list of user-identifiers is returned. - If passed an authentication token and an action of
user_groups
then the full profile data is returned for each person.
The documentation for the Site members web-hook has more details about how the hook works, including examples.
The web-hook /gs-group-member-leave.json
removes a person from a group. The hook takes
- The authentication token (
token
), - A group identifier (
groupId
), and - A user-identifier (
userId
).
The documentation for the Leave group web-hook has more details about how the hook works, including examples.
If you only have an email-address for the person, then you should retrieve a single profile first to determine the user identifier (:jsid
).
The profile is also useful for removing someone from a site. A person is removed from a site when they are removed from all groups on the site: so by iterating through the list of groups (:jsgroups
) you will eventually remove someone from the site.