Notification Callback is a service that can be enabled to notify you when a submission log 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 it works
The callback will be an HTTP(S) request to a URL (notify-url) provided by the member with all data relayed via HTTP 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 HTTP headers are provided:
- CROSSREF-NOTIFY-ENDPOINT: the notify-endpoint2 (Required)
- 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 Crossref with regards to the request. (Optional)
- CROSSREF-RETRIEVE-URL: the URL for the member to use to retrieve the request's result. Since the HTTP 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. See format specification in RFC 2616.
- CROSSREF-RETRIEVE-URL-EXPIRATION-DATE: the timestamp after which service result is no longer available at the given retrieve-url3.
Setting up an endpoint
You'll need to set up and register an endpoint to receive callbacks.
- Create an endpoint using curl:
curl -s -D - "http://0-doi.crossref.org.wam.leeds.ac.uk/notification-callback/exec/setNotifyEndpoint\
- Test your endpoint:
curl -s -D - "http://0-doi.crossref.org.wam.leeds.ac.uk/notification-callback/exec/createNotificationCallback\
After a few minutes your end-point will receive a callback with your test payload message.
- Contact us to activate the service - we'll need:
- your endpoint info (notify-endpoint and notify-url)
- 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
For the submission 1368966558 the notification would be as follows (new lines have been added between header name and header value to improve readability):
Fri, 11 Jul 2014 21:08:24 GMT
Fri, 18 Jul 2014 21:08:24 GMT
Querying for Past Callbacks
The notification callback service can be queried for past callbacks. The query is is implemented as an HTTP 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 timestamp use the ISO 8061 format YYYY-MM-DD’T’hh:mm:ss’Z’, eg “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:
"notify-url" : "http://abc.org/crossref/callbacks",
"date" : "2014-07-14T21:09:00Z",
"explanation": "http status 200"
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 HTTP 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 query service is currently available at:
- 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 Crossref 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 Crossref 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 HTTP headers so as to be HTTP method (POST, PUT, etc) neutral.
- 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 Crossref 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 credentials are provided by Crossref.