HipChat to add-on HTTP calls
Any request made by HipChat to your add-on configuration page will include a JSON Web Token (JWT), an encoded form of JSON data and a signature to verify its contents. It is recommended you use one of the existing JWT libraries to decode the token. You can use the JWT token to validate that:
- The request comes from HipChat
- The request comes from the right installation
- The request was not altered in transit
The JWT token is included either:
- in the HTTP header "Authorization"
- in the request parameter: "signed_request"
JWT tokens are base64 encoded. Once decoded, the JWT token is made of 3 elements delimited by a "."
The payload contains the following elements, which provide contextual information about the call:
||Issuer: OAuth Client ID|
||Subject: User ID|
||Issued at timestamp|
||JWT ID (random 20 chars)|
The token is signed. You can verify its signature using the sharedSecret sent during installation.
Here are the steps to handle a JWT token:
- Extract the token from the request. Depending on the call:
- from the HTTP header "Authorization"
- from the request parameter: "signed_request"
- Decode the base64-encoded token
- Extract the oauthId which is in the 'iss' (issuer) parameter from the JWT token
- Lookup the installation data received via the Installation flow for this oauthId
- Use the sharedSecret from the installation data to validate the signature of the token
For example, using Node.js:
Add-on front-end to add-on backend calls
This token has the same structure as the one used for HipChat to add-on calls.
In particular, it contains the context of the call (oauth client ID, user ID, etc.).