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.
How do I get “/read-public” access token?
Anyone with public or member API credentials can receive a /read-public access token. 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.
An example call to obtain an access token to read public data on the sandbox — replace the placeholders with your credentials (be sure to remove the brackets.
URL=https://sandbox.orcid.org/oauth/token
HEADER: Accept: application/json
METHOD: POST
DATA:
client_id=[Your public API client ID]
client_secret=[Your public API secret]
grant_type=client_credentials
scope=/read-public
You will then be returned an access token similar to the following. The token returned is long-lived (not expiring for approximately 20 years) and can be used multiple times to retrieve public data from ORCID records.
{"access_token":"4bed1e13-7792-4129-9f07-aaf7b88ba88f","token_type":"bearer",
"refresh_token":"2d76d8d0-6fd6-426b-a017-61e0ceda0ad2","expires_in":631138518,
"scope":"/read-public","orcid":null}
Note: All tokens with the /authenticate scope now also have /read-public scope included. If you use only the /authenticate scope, you can use the stored access tokens to read public data without needing to again obtain an access token.
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.
How do I register a webhook?
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/updated
becomes
https%3A%2F%2Fnowhere2.com%2F0000-0002-7465-2162%2Fupdated
Build 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%2Fupdated
Register 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%2Fupdated HEADER: Accept: application/json HEADER: Authorization: Bearer [Your access token] HEADER: Content-Length: 0 METHOD: PUT
The response should be a 201 Created, but if the callback already existed, then the response will be 204 No Content.
HTTP/1.1 201 Created Server: nginx/1.1.19 Connection: keep-alive Location: https://api.sandbox.orcid.org/0000-0002-7465-2162/webhook/https%3A%2F%2Frequestb.in%2Fz57lzcz5
Receiving 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.
What does a webhook callback look like?
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/updated
Your 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 Content
Any 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.
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.
How do I unregister a webhook?
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: DELETE
The 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