Registering a notification webhook

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