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
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.
{
"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"
}