This tutorial will walk you through setting up and testing webhooks on an ORCID record. Webhooks change notifications are an ORCID premium member feature that enable applications to be informed when 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. (Note: 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’ll register a callback URL for each authenticated ORCID iD that you are watching, and we will notify that URL when there are changes to the ORCID record.
ORCID members can get a client ID and secret after having demonstrated an integration to the ORCID Staff.
Generate a webhooks access token
First you 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.
| Parts of a cURL statement to get a webhooks access token | ||
|---|---|---|
| Accept Header | The format for the call response, either XML or json | -H "Accept: application/json" |
| client_id | Your client id from your credentials | -d "client_id=APP-NPXKK6HFN6TJ4YYI" |
| client_secret | Your client secret from your credentials | -d "client_secret=060c36f2-cce2-4f74-bde0-a17d8bb30a97" |
| Scope | The scope you want for the access token, in this case /webhook | -d "scope=/webhook" |
| Grant Type | The from of request, in this case client credentials | "grant_type=client_credentials" |
| URI | The address to sent this request to | "https://sandbox.orcid.org/oauth/token" |
Complete cURL statement
curl -i -L -H "Accept: application/json" -d "client_id=APP-NPXKK6HFN6TJ4YYI" -d "client_secret=060c36f2-cce2-4f74-bde0-a17d8bb30a97" -d "scope=/webhook" -d "grant_type=client_credentials" "https://sandbox.orcid.org/oauth/token"
Example response to cURL statement
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Date: Fri, 05 Apr 2013 13:05:01 GMT
{"access_token":"5eb23750-1e19-47a3-b6f6-26635c34e8ee",
"token_type":"bearer",
"refresh_token":"c7d3d5fd-e4c0-4825-89f2-7cfb4a1cf01e",
"expires_in":631138518,
"scope":"/webhook"}
Register a Webhook
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.
curl -v -H "Accept: application/json" -H "Authorization: Bearer 5eb23750-1e19-47a3-b6f6-26635c34e8ee" -H "Content-Length: 0" -X PUT "https://api.sandbox.orcid.org/0000-0002-7465-2162/webhook/https%3A%2F%2Fnowhere2.com%2F0000-0002-7465-2162%2Fupdated"
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
Unregister a Webhook
The URL for unregistering a webhook is the same as for registering. However, you need to use the HTTP DELETE method.
curl -v -H "Accept: application/json" -H "Authorization: Bearer 5eb23750-1e19-47a3-b6f6-26635c34e8ee" -H "Content-Length: 0" -X DELETE "https://api.sandbox.orcid.org/0000-0002-7465-2162/webhook/https%3A%2F%2Fnowhere2.com%2F0000-0002-7465-2162%2Fupdated"
The response should be 204 No Content.
HTTP/1.1 204 No Content Server: nginx/1.1.19 Date: Mon, 29 Jul 2013 14:36:11 GMT
Receiving the webhook call
Now that you have registered your 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. 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.