This version is in beta - expect some breaking changes.

Push Pull Notifications API

Dates and amounts
Date Amount
Version and status
Available in Sandbox Yes
Sandbox base URL https://test-api.service.hmrc.gov.uk
Available in Production Yes
Production base URL https://api.service.hmrc.gov.uk

Overview

Use the Push Pull Notifications API to get notifications (pull) and to send notifications (push) automatically.

Other HMRC APIs create notifications in response to events like asynchronous API requests.

Check if the HMRC API you are using supports Push Pull Notifications in the API documentation.

Notifications will be deleted after 30 days.

Push notifications

You can enter a Push/Callback URL after subscribing to an HMRC API that supports Push Pull Notifications.

Created notifications are sent automatically by a POST request to the Push/Callback URL.

For example, if the Push/Callback URL is set to https://www.example.com/push when a notification is created, a POST request is sent to https://www.example.com/push with a body similar to:

{     "notificationId": "1ed5f407-8096-40d1-87ef-9a2a103eeb85",     "boxId": "50dca3fc-c37c-4f03-b719-63571333624c",     "messageContentType": "application/json",     "message": "{\"key\":\"value\"}",     "status": "PENDING",     "createdDateTime": "2020-06-01T10:20:23.160+0000" }

See get a list of notifications for details about the structure of this JSON object.

When a notification is pushed its status will be PENDING. If your service responds to this request with an HTTP status code 200, the notification status is updated to ACKNOWLEDGED.

If your service responds with a different HTTP status code, the notification status will remain as PENDING and the request is retried several times over the next few hours.

If after a few hours, an HTTP status code 200 has not been received, the notification status is updated to FAILED.

Validating the callback URL

When you save a callback URL to receive push notifications from an API, the system will try to verify it by sending a GET request to the callback URL with the query parameter “challenge”.

You should return a 200 response with the challenge in the JSON response body. For example:

{
  “challenge”: “challenge_from_query_parameter”
}

If we don’t receive a successful response with a matching challenge within 20 seconds, the request to save the callback URL will fail.

You will see an error message to inform you that the callback URL is invalid.

Push Secret

When you subscribe to an API that sends Push notifications, we will generate a push secret you can use to validate the payload signature and confirm notifications come from HMRC.

Validate the payload signature

Using the push secret, HMRC will generate a signature of the payload for every notification sent to the callback URL.

That signature will be available in the HTTP header called X-Hub-Signature.

When receiving a notification, you should compute the signature of the payload using the push secret and verify that it matches the value in the X-Hub-Signature header.

The signature is calculated using HMAC-SHA1 and converted to hexadecimal format. For example (example in Scala)

import java.nio.charset.StandardCharsets.UTF_8
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec

def sign(pushSecret: String, payload: String): String = {
 val secretKey = new SecretKeySpec(pushSecret.getBytes(UTF_8), "HmacSHA1")
 val mac = Mac.getInstance("HmacSHA1")
 mac.init(secretKey)
 mac.doFinal(payload.getBytes(UTF_8)).map("%02x".format(_)).mkString
}

Using sample key as a pushSecret and {"sample": "payload"} as a payload, will return the signature c6cdd3e30021fe66d88d37088fed2566453eb7fb.

Pull notifications

Regardless of whether a Push/Callback URL is set up, notifications can be retrieved by polling get a list of notifications.

Avoid breaking our rate limits and call the endpoint no more than once every 10 seconds.

You will need a Box Identifier to use this endpoint. A Box Identifier is made available by the HMRC API you are using.

When you have successfully processed the notification, you can update its status to ACKNOWLEDGED by calling the acknowledge a list of notifications endpoint.

Notification statuses

  • PENDING means the notification was created but has not been processed
  • FAILED means the notification was pushed to your Push/Callback URL, but no HTTP status code 200 was returned
  • ACKNOWLEDGED means the notification was successfully pushed to your Push/Callback URL or you processed the notification using the acknowledge a list of notifications endpoint

Processing notifications

The way to process notifications is different for each HMRC API. Check the documentation for the HMRC API you are using.

Notification messages should include information like a correlation or request identifier that allows notifications to be identified.

Versioning

When an API changes in a way that is backwards-incompatible, we increase the version number of the API. See our reference guide for more on versioning.

Errors

We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

  • 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
  • 400 to 499 if it failed because of a client error by your application
  • 500 to 599 if it failed because of an error on our server

Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.

Testing

Subscribe to an HMRC API that supports Push Pull Notifications and read the documentation for testing guidance.

Skip to main content

Endpoints

/misc/push-pull-notification/box/{boxId}/notifications

Get a list of notifications
GET

Returns a list of notifications that have been sent to a box.

A maximum of 100 notifications will be returned. These will be ordered oldest first.

The OAuth bearer token used by this endpoint must have the scope read:pull-notifications.

Authorisation

This endpoint is application-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:pull-notifications scope.

Path parameters

Path parameters table
Name Description
boxId
string
required

Unique identifier for a box

For example: 50dca3fc-c37c-4f03-b719-63571333624c

Query parameters

Query parameters table
Name Description
status
string
optional

Only return notifications with this status.
Either PENDING, FAILED or ACKNOWLEDGED.

For example: FAILED

fromDate
string
optional

Only return notifications created after this datetime.
ISO-8601 UTC date and time.

For example: 2020-06-03T14:20:54.987

toDate
string
optional

Only return notifications created before this datetime.
ISO-8601 UTC date and time.

For example: 2020-06-03T14:20:54.987

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.0+json
Authorization
required
An OAuth 2.0 Bearer Token with the read:pull-notifications scope.

For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

See also fraud prevention.

Response

HTTP status: 200 (OK)

[
  {
      "notificationId": "1ed5f407-8096-40d1-87ef-9a2a103eeb85",
      "boxId": "50dca3fc-c37c-4f03-b719-63571333624c",
      "messageContentType": "application/json",
      "message": "{\"key\":\"value\"}",
      "status": "PENDING",
      "createdDateTime": "2020-06-01T10:20:23.160+0000"
  },
  {
      "notificationId": "86bb5f82-452e-49c8-88af-1f321d573960",
      "boxId": "50dca3fc-c37c-4f03-b719-63571333624c",
      "messageContentType": "application/xml",
      "message": "<someXml>xmlValue</someXml>",
      "status": "PENDING",
      "createdDateTime": "2020-06-02T10:27:33.613+0000"
  }
]

Response table
Name Description
notificationId
string
required

Unique identifier for a notification.

For example: 86bb5f82-452e-49c8-88af-1f321d573960

boxId
string
required

Unique identifier for a box the notification was sent to.

For example: 50dca3fc-c37c-4f03-b719-63571333624c

messageContentType
string
required

Content type of the message.

Limited to the following possible values:

application/json
application/xml
message
string
required

The notification message defined by messageContentType (JSON or XML). If this is JSON then it will have been escaped. Details on the structure of this data can be found in the documentation for the HMRC API that created the notification.

For example: {\"key\":\"value\"}

status
string
required

Status of the notification.

Limited to the following possible values:

PENDING
FAILED
ACKNOWLEDGED
createdDateTime
string
required

ISO-8601 UTC date and time the notification was created.

For example: 2020-06-01T10:27:33.613+0000

Error scenarios

Error scenarios table
Scenario HTTP status Code

The box identifier is not valid

400 (Bad Request)

BAD_REQUEST

The provided query parameters don't match the specification

400 (Bad Request)

INVALID_REQUEST_PAYLOAD

You do not have access to the specified box

403 (Forbidden)

FORBIDDEN

The unique identifier for the box does not exist

404 (Not Found)

BOX_NOT_FOUND

The accept header is missing or invalid

406 (Not Acceptable)

ACCEPT_HEADER_INVALID

For error scenarios that are common across all APIs, and for error formats, see our reference guide.


Close Section
/misc/push-pull-notification/box/{boxId}/notifications/acknowledge

Acknowledge a list of notifications
PUT

Updates the status of one or more notifications to ACKNOWLEDGED.

A maximum of 100 notifications will be updated.

The OAuth bearer token used by this endpoint must have the scope write:notifications.

Authorisation

This endpoint is application-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:notifications scope.

Path parameters

Path parameters table
Name Description
boxId
string
required

Unique identifier for a box

For example: 50dca3fc-c37c-4f03-b719-63571333624c

Request headers

Request headers Table
Name Description
Content-Type
required

The format of the request body. This must be application/json.

For example: application/json
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.0+json
Authorization
required
An OAuth 2.0 Bearer Token with the write:notifications scope.

For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

See also fraud prevention.

Request

{
  "notificationIds": [
    "50dca3fc-c37c-4f03-b719-63571333624c",
    "86bb5f82-452e-49c8-88af-1f321d573960"
  ]
}

Request table
Name Description
notificationIds
array
required

Unique identifier for a notification.

For example: 86bb5f82-452e-49c8-88af-1f321d573960

Response

HTTP status: 204 (No Content)

Error scenarios

Error scenarios table
Scenario HTTP status Code

The request body does not match the specification

400 (Bad Request)

INVALID_REQUEST_PAYLOAD

You do not have access to the specified box

403 (Forbidden)

FORBIDDEN

The unique identifier for the box does not exist

404 (Not Found)

BOX_NOT_FOUND

The Accept header is missing or invalid

406 (Not Acceptable)

ACCEPT_HEADER_INVALID

The Content-Type header is incorrect

415 (Unsupported Media Type)

BAD_REQUEST

For error scenarios that are common across all APIs, and for error formats, see our reference guide.


Close Section

Skip to main content