Basic tutorial: Webhooks notifications

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.