Setting up webhooks

When you use our Letter Processing Service, either through the API or the App, you can get notifications of the letters being processed in real time via webhooks.

Index

  1. Create a webhook
    1. Headers
    2. Triggers
    3. Return fields
  2. Variable interpolation

Create a webhook

Webhooks are created from the "Developer tools" section of the API app . Webhooks will react to all letters uploaded in the organization, despite who created them. The required fields are the name, HTTP method used for calling back your server, and the URL that will be called. Next, you can set up Headers, Triggers, and Return fields.

Headers

Webhooks allow you to add any number of HTTP headers that will be used on each outgoing request to your server. You can use these for any need, or not use them at all. You will probably want to use at least one header to authenticate calls in your system.

Webhooks will honor all custom headers except for those that are set by our system itself, in which case the values set in the webhook will be ignored. These headers are:

The values of the HTTP headers support Variable interpolation.

Triggers

Triggers define under what events should a webhook be called. Each uploaded letter will go thorugh a series of statuses in our system, and you can choose to call your webhooks on any or all of them.

Check the possible letter status here.

Return fields

The body of each outgoing call will contain information about the letter that was updated and the data that was extracted. Not all the return fields will contain data in all letter statuses.

The payload is sent in JSON format and supports Variable interpolation. The following is an example of a complete request body for a webhook that had selected all return fields. 

{
 "job": {
  "id": "0",
  "insert_time": "2022-06-21 22:36:59.792139+00:00"
 },
 "id": 0,
 "status": "READY",
 "filename": "test-letter1.jpg",
 "method": "CLASSIFIER",
 "payload": "{\"student_id\": \"your_custom_student_id\"}",
 "insert_time": "2022-06-21 22:36:59.792348+00:00",
 "aid_amounts": [
  {
   "value": 3900.05,
   "program": "PELL",
   "source": "FEDERAL",
   "category": "GRANT",
   "description": "Test Federal Pell Grant",
   "term": "ANNUAL",
   "insert_time": "2022-06-21 22:36:59.787642+00:00"
  },
  {
   "value": 1750.0,
   "program": "SUBSIDIZED",
   "source": "FEDERAL",
   "category": "LOAN",
   "description": "Test Federal Direct Subsidized Loan",
   "term": "SPRING",
   "insert_time": "2022-06-21 22:36:59.788151+00:00"
  },
  {
   "value": 1.0,
   "program": "UNIDENTIFIED",
   "source": "INSTITUTIONAL",
   "category": "SCHOLARSHIP",
   "description": "Test DecidED Scholarship",
   "term": "SUMMER",
   "insert_time": "2022-06-21 22:36:59.788554+00:00"
  }
 ],
 "cost_amounts": [
  {
   "value": 13290.55,
   "description": "Test Housing and meals",
   "categories": [
    "HOUSING",
    "MEALS"
   ]
  },
  {
   "value": 40000.0,
   "description": "Test Tuition and Fees",
   "categories": [
    "TUITION",
    "FEES"
   ]
  }
 ]
}

Variable interpolation

Some of the webhook's fields can contain variables that are resolved at the time of calling it with a particular letter. This is useful if you want to have some fields of the letter in other parts of the request besides the body. For example, you may want the Job's id in a custom header.

Variable interpolation is currently supported in the URL and in the Headers' values. The syntax is the same one used by Python: variables go between curly braces and if you need to use literal curly braces, you double them.

The currently available variables are:

Examples