This tutorial will walk you through the individual steps to set up and test webhooks on an ORCID record.
Webhooks change notifications are an ORCID premium member feature that enable applications to be informed when public data within an ORCID record changes. This feature allows premium members to stay up-to-date on new information, or even trigger events in their own systems based on an activity. Please note that the actual data exchange is based on privacy levels set by the ORCID iD holder, and permissions the individual has granted to the member organization.
Using the API and your member API client credentials, you can register a callback URL for each ORCID iD that you are watching, and we will notify that callback URL when changes occur on the ORCID record.
Obtain a webhooks access token
In order to use the webhook feature you will need to generate an access token that allows you to create webhooks. This process only needs to be completed once, the same access token can then be used to create webhooks on multiple ORCID records.
Anyone premium member can obtain a ‘/webhook’ access token. A single token can be used to register webhooks for multiple records. To obtain a token, you make a call to the ORCID API token endpoint.
This process is often referred to as the client-credentials OAuth flow, or 2-step OAuth.
Below is an example call to obtain the access token — replace the placeholders with your credentials (be sure to remove the brackets.)
curl -i -L -H "Accept: application/json"
-d "client_id=(your client ID)"
-d "client_secret=(your client secret)"
-d "scope=/webhook"
-d "grant_type=client_credentials"
"https://sandbox.orcid.org/oauth/token"You will then be returned an access token similar to the following.
{"access_token":"5eb23750-1e19-47a3-b6f6-26635c34e8ee",
"token_type":"bearer",
"refresh_token":"c7d3d5fd-e4c0-4825-89f2-7cfb4a1cf01e",
"expires_in":631138518,
"scope":"/webhook"}
3
1
Register a webhook
Once you have obtained your webhooks access token you will be able to start registering webhooks. You can register a webhook against an ORCID iD without the users permission as the functionality is only looking at public data that is available on the users ORCID record.
Webhooks can be registered by premium members against any ORCID record in the registry. The steps are:
Encode the URL
URL-encode the URL that you want ORCID to call when the user‚s record is updated. For example the following URL:
https://nowhere2.com/0000-0002-7465-2162/updatedbecomes
https%3A%2F%2Fnowhere2.com%2F0000-0002-7465-2162%2FupdatedBuild the URL
Build the full URL for the ORCID API call starting with the URL of the ORCID record then adding ‚√∫/webhook‚√π and the URL you want called. So it should look like https://api.sandbox.orcid.org/{ORCID}/webhook/{URL-ENCODED-WEBHOOK-URL}
For example, using the webhook URL above and the ORCID iD 0000-0002-7465-2162, the full URL is:
https://api.sandbox.orcid.org/0000-0002-7465-2162/webhook/https%3A%2F%2Fnowhere2.com%2F0000-0002-7465-2162%2FupdatedRegister the webhook
Use your webhooks‚ access token to register your webhook against the user‚s ORCID record. You need to use an HTTP PUT request, but you should not include anything in the body of the request.
URL= https://api.sandbox.orcid.org/0000-0002-7465-2162/webhook/https%3A%2F%2Fnowhere2.com%2F0000-0002-7465-2162%2Fupdatedn HEADER: Accept: application/json HEADER: Authorization: Bearer [Your access token]n HEADER: Content-Length: 0n METHOD: PUTThe response should be a 201, but if the callback already existed, then the response will be 204.
HTTP/1.1 201nServer: nginx/1.1.19nConnection: keep-alive Location: https://api.sandbox.orcid.org/0000-0002-7465-2162/webhook/https%3A%2F%2Frequestb.in%2Fz57lzcz5Receiving the webhook call
Once you have registered a webhook URL, you will get a callback when the user’s ORCID record is updated. Hook notifications are sent every five minutes to avoid multiple calls for a single user session.
The ORCID Registry will do the following HTTP call when a record is updated. The request uses the HTTP POST method, but the body of the request is empty.
curl -v -X POST https://nowhere2.com/0000-0002-7253-3645/updatedYour server should respond with standard HTTP response codes. So, if the call was successful you should return 204 No Content.
HTTP/1.1 204 No ContentAny 2xx response code means that the call was successful. If you return a code that is not a 2xx, then we will retry the call five minutes later.
0
0
Unregistering a webhook
You can unregister a webhook from an ORCID iD if you no longer want to synchronise data within your own system with that specific ORCID.
The URL for unregistering a webhook is the same as for registering. However, you need to use the HTTP DELETE method.
URL= https://api.sandbox.orcid.org/0000-0002-7465-2162/webhook/https%3A%2F%2Fnowhere2.com%2F0000-0002-7465-2162%2Fupdated
HEADER: Authorization: Bearer [Your access token]
HEADER: Content-Length: 0
METHOD: DELETEThe response should be 204 No Content.
HTTP/1.1 204 No Content
Server: Apache-Coyote/1.1
Date: Fri, 05 Apr 2013 12:49:17 GMT