Status Webhook API - department-of-veterans-affairs/caseflow GitHub Wiki

Purpose

The purpose of this webhook API is to give Caseflow a way to receive real-time updates from VA Notify so the notification statuses are kept current and to also avoid losing information due to the notifications "expiring" in VA Notify and being removed from their API.

Workflow

When certain events trigger in Caseflow a request will be sent to the VA Notify API to generate and send the notification while sending the info back over to Caseflow. The webhook will be directly connected to the VA Notify Platform to track any status changes to notifications and send that over to Caseflow which would then update the corresponding status in the database.

VA Notify Status Sequence Diagram

Notification Update Diagram

Data and Routes

The webhook will be using POST /idt/api/v1/va_notify_update endpoint to send the payload over to Caseflow with the updated status.

Payload

{
  "id": "string",
  "body": "string",
  "completed_at": "string",
  "created_at": "string",
  "created_by_name": "string",
  "email_address": "string",
  "line_1": "string",
  "line_2": "string",
  "line_3": "string",
  "line_4": "string",
  "line_5": "string",
  "line_6": "string",
  "phone_number": "string",
  "postage": "string",
  "postcode": "string",
  "recipient_identifiers": [
    {
      "id_type": "string",
      "id_value": "string"
    }
  ],
  "reference": "string",
  "scheduled_for": "string",
  "sent_at": "string",
  "sent_by": "string",
  "status": "string",
  "subject": "string",
  "template": {
    "id": "string",
    "uri": "string",
    "version": number
  },
  "type": "string"
}

Data Definitions

Data	Description
id	ID of the notification
body	The body of the notification
completed_at	The timestamp on when the notification was delivered
created_at	The timestamp on when the notification was created
created_by_name	Name of the person who sent notification if sent manually
email_address	Email address of recipient if type is email
line_1	First line of address if type is letter
line_2	Second line of address if type is letter
line_3	Third line of address if type is letter
line_4	Fourth line of address if type is letter
line_5	Fifth line of address if type is letter
line_6	Sixth line of address if type is letter
phone_number	The phone number of the recipient is type is sms
postage	First or Second class if type is letter
postcode	Postcode of recipient is type is letter
recipient_identifiers[].id_type	The type of ID used to lookup recipient info
recipient_identifiers[].id_value	The ID that will used to lookup recipient info
reference	Optional reference string
scheduled_for	Timestamp on when notification will be sent
sent_at	Timestamp of when notification as sent
sent_by	The person who sent the notification
status	The status of the notification
subject	The subject of the notification
template[].id	The ID of the template being used
template[].uri	The URI of the template being used
template[].version	The version of the template being used
type	The type of notification being sent

Status Dictionary

Payload Status	Caseflow Status
sent	Pending Delivery
temporary-failure	Pending Delivery
delivered	Delivered
permanent-failure	Failed Delivery
technical-failure	Failed Delivery
preferences-declined	Opted-out

Sample

Generate a token and place it onto the Authorization tab and select Bearer Token from the dropdown. Copy from the result of this command

key=ApiKey.create!(consumer_name: "new")
key.key_string

Make sure to have a notification that exists with this ID. You can create a new notification using this command in the console

Email

Notification.create(appeals_id: Appeal.find_by_id(10).uuid, appeals_type: "Appeal", event_date: Date.today, event_type: "Hearing scheduled", notification_type: "Email", email_notification_external_id: "3fa85f64-5717-4562-b3fc-2c963f66afa9")

SMS

Notification.create(appeals_id: Appeal.find_by_id(10).uuid, appeals_type: "Appeal", event_date: Date.today, event_type: "Hearing scheduled", notification_type: "SMS", sms_notification_external_id: "3fa85f64-5717-4562-b3fc-2c963f66afa6")

These are example payloads.

Email

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "body": "string",
  "completed_at": "2023-04-17T12:38:48.699Z",
  "created_at": "2023-04-17T12:38:48.699Z",
  "created_by_name": "string",
  "email_address": "[email protected]",
  "line_1": "string",
  "line_2": "string",
  "line_3": "string",
  "line_4": "string",
  "line_5": "string",
  "line_6": "string",
  "phone_number": "+16502532222",
  "postage": "string",
  "postcode": "string",
  "recipient_identifiers": [
    {
      "id_type": "VAPROFILEID",
      "id_value": "string"
    }
  ],
  "reference": "string",
  "scheduled_for": "2023-04-17T12:38:48.699Z",
  "sent_at": "2023-04-17T12:38:48.699Z",
  "sent_by": "string",
  "status": "created",
  "subject": "string",
  "template": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "uri": "string",
    "version": 0
  },
  "type": "email"
}

SMS

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "body": "string",
  "completed_at": "2023-04-17T12:38:48.699Z",
  "created_at": "2023-04-17T12:38:48.699Z",
  "created_by_name": "string",
  "email_address": "[email protected]",
  "line_1": "string",
  "line_2": "string",
  "line_3": "string",
  "line_4": "string",
  "line_5": "string",
  "line_6": "string",
  "phone_number": "+16502532222",
  "postage": "string",
  "postcode": "string",
  "recipient_identifiers": [
    {
      "id_type": "VAPROFILEID",
      "id_value": "string"
    }
  ],
  "reference": "string",
  "scheduled_for": "2023-04-17T12:38:48.699Z",
  "sent_at": "2023-04-17T12:38:48.699Z",
  "sent_by": "string",
  "status": "created",
  "subject": "string",
  "template": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "uri": "string",
    "version": 0
  },
  "type": "sms"
}