Crossref holds metadata for approximately 150 million scholarly artifacts. These range from peer reviewed journal articles through to scholarly books through to scientific blog posts. In fact, amid such heterogeneity, the only singular factor that unites such items is that they have been assigned a document object identifier (DOI); a unique identification string that can be used to resolve to a resource pertaining to said metadata (often, but not always, a copy of the work identified by the metadata).
We’re equally sad and proud to report that Rachael Lammey is moving on in her career to the very lucky team at 67Bricks. Her last day at Crossref is today, Friday 16th February. Which is too soon for us, but very exciting for her!
It’s hard to overstate Rachael’s impact on Crossref’s growth and success in her 12 years here. She started as a Product Manager where she developed that role into a broad and central function, and soon moved into the newly-formed community team as International Outreach Manager where she grew important programs such as Sponsors, Ambassadors, a series of ‘LIVE’ events around the world, and she went on to manage her own team and establish some of the most important strategic relationships that Crossref now feels fortunate to have.
Great news to share: our Executive Director, Ed Pentz, has been selected as the 2024 recipient of the Miles Conrad Award from the USA’s National Information Standards Organization (NISO). The award is testament to an individual’s lifetime contribution to the information community, and we couldn’t be more delighted that Ed was voted to be this year’s well-deserved recipient.
During the NISO Plus conference this week in Baltimore, USA, Ed accepted his award and delivered the 2024 Miles Conrad lecture, reflecting on how far open scholarly infrastructure has come, and the part he has played in this at Crossref and through numerous other collaborative initiatives.
Metadata about research objects and the relationships between them form the basis of the scholarly record: rich metadata has the potential to provide a richer context for scholarly output, and in particular, can provide trust signals to indicate integrity. Information on who authored a research work, who funded it, which other research works it cites, and whether it was updated, can act as signals of trustworthiness. Crossref provides foundational infrastructure to connect and preserve these records, but the creation of these records is an ongoing and complex community effort.
Notification callback is a service you can use to notify you when a submission log, either in the test or production admin tool, is available for a metadata, batch query, or Cited-by query submission. Notification is provided in the form of a HTTP(S) URL where the log can be retrieved. If the notification callback service is enabled, you will no longer receive submission log emails.
How the notification callback service works
The callback will be an HTTP(S) request to a URL (notify-url) provided by the member with all data relayed via HTTPS headers. The notification specifies the availability of the result, some context of the request, and an HTTP(S) URL from which to get the result. The submission log may then be retrieved using the HTTP(S) URL.
The headers use the simple name and value structure; that is, the value has no additional structure that divides it into parts. To ensure that all Unicode values can be accommodated all header values will be UTF-8 encoded.
When the notify-url is used the following HTTPS headers are provided:
CROSSREF-NOTIFY-ENDPOINT: the notify-endpoint (required) is just the name used to identify the specific notification (more on this below)
CROSSREF-EXTERNAL-ID: the id given by the member with regards to the request. For metadata deposits, for example, it is the value of the doi_batch_id element (Optional)
CROSSREF-INTERNAL-ID: the id given by us with regards to the request (Optional)
CROSSREF-RETRIEVE-URL: the URL for the member to use to retrieve the request’s result. Since the HTTPS header value is UTF-8 encoded, the URL will contain no URI encodings. For example, an Á will not be encoded as %C3%81
CROSSREF-SERVICE-DATE: the date and time stamp of the service request. Learn more about format specification in RFC 2616.
CROSSREF-RETRIEVE-URL-EXPIRATION-DATE: the timestamp after which service result is no longer available at the given retrieve-url.
Setting up an endpoint
You’ll need to set up and register an endpoint to receive callbacks.
your endpoint info (notify-endpoint and notify-url) – the notify-endpoint is just a name to identify the specific notification. The notify-endpoint should be something you can recognize so when you receive responses that include the endpoint name, it is easy to know which of the callback feeds it is coming from. Thenotify-url has to be the actual URL of your callback receiver, as that is where the notification callback transmits to via http/https
the services you’re activating the service for (metadata submissions, batch querying, Cited-by alerts)
the username and/or DOI prefix you’ll be using
if configuring the notification callback service for Cited-by alerts, you’ll need to provide us with the email address that was used to set your fl_query alerts
Make sure you inform us of any changes to your endpoint: if a message fails to send we will retry for up to a week after which you will no longer be able to receive it.
Example of a notification
For the submission 1368966558 the notification would be as follows (new lines have been added between header name and header value to improve readability):
The notification callback service can be queried for past callbacks. The query is implemented as an HTTPS service (access control and limits to end-points and time frames TBD).
The query takes 3 criteria, the notify-endpoints, an inclusive from timestamp, and an exclusive until timestamp. All timestamps use the ISO 8061 format YYYY-MM-DD’T’hh:mm:ss’Z, for example, 2014-07-23T14:43:01Z.
The query results in a JSON array of callbacks. For example, querying for the single endpoint “1CFA094C-4876-497E-976B-6A6404652FC2” returns:
A flat structure is used to aid processing the result as a stream. There is no order defined.
The audit item is a record of attempted callbacks. It details the notify-endpoint’s notify-url used at the time of the callback, the timestamp of the callback, and the HTTPS status of the callback. If more than one attempt has been tried then the audit array will contain multiple elements; there is no order defined.
The usr and pwd are your Crossref username and password. The ENDPOINT value is a notify-endpoint or a space separated set of notify-endpoints.
A note on trusting Let’s Encrypt
We use Let’s Encrypt, a global Certificate Authority, to enable secure HTTPS connections. Please ensure your local certificate library is updated to include the letsencrypt root certificate before requesting a notification callback for your account/prefix.
Glossary of notification callback service terms
notify-url: the URL that the member provides and is used to notify them of the availability of a service request’s result. How the URL is provided to us will depend on the service.
notify-endpoint: an opaque token used to select a notify-url. The token will be anonymous and difficult to guess. The notify-endpoint is provided by the member. The notify-endpoint is associated with one notify-url (many notify-endpoints can be associated with the same notify-url).
retrieve-url: the URL that we provides that is used by the member to get the service request result.
notify-payload: the data that specifies what service request this notification is for. This payload will use HTTPS headers so as to be HTTPS method-neutral (such as POST, PUT).
retrieve-payload: the service result. Each service will define its own result content-type (that is very much like what would be sent in email today).
notification-authentication: This is the method of authentication we will use with the notify-url. Credentials are provided by the member.
retrieval-authentication: This is the method of authentication the member will use with the retrieve-url. The account credentials are provided by us.
Page owner: Isaac Farley | Last updated 2023-November-29