Notifications API

You can use the Notifications API to tell the archive who to notify, for example when an ingest fails or a SIP has a virus. A notification configuration links one event to one channel. The channel is an email, a webhook call, or an event log that you can report on.

Every call needs the headers in Common headers.

Events you can be notified about

Set eventType to one of these values. Each event has a fixed severity, which you can filter on with event_severity.

Channels

Set actionType to the channel, and put its settings in configuration:

• EMAIL: sends an HTML email to the address in destination_mail.

• WEBHOOK: sends a POST request to the URL in destination_url, with Content-Type: application/json. You can add your own headers in headers. If the call fails, the archive tries again up to three times, after 1, 2, and 4 seconds.

• COLLECTION: logs each event in the event log that you name in destination_collection. To turn these events into a report, create a report_collection_query report in the Reports API.

Write the message template

notification_template is a FreeMarker template. The archive fills it in for each event, and sends the result as the email body or the webhook body. For a webhook, make sure that the result is the JSON that your endpoint expects.

You can use these variables:

For documentRemoved, message and severity have no value. A template that uses them sends nothing, so use only name, packageId, packageType, and time.

For example, a webhook template that sends JSON:

{
  "event": "${name}",
  "severity": "${severity}",
  "package": "${packageId}",
  "message": "${message}"
}

When you save the configuration, the archive tries the template with sample values for every severity and package type. If the template uses a variable that isn't in the list, or can't be processed, the save fails.

List notification configurations

GET /v2/notifications/configs

Required role: archive-content-manager

Response: 200 OK with a NotificationConfigList, sorted by name.

Get a notification configuration

GET /v2/notifications/configs/{configId}

Required role: archive-content-manager

Response: 200 OK with a NotificationConfig.

• 404: there's no notification configuration with this ID.

Create a notification configuration

Sets up a notification. It applies to the events that happen after you save it.

POST /v2/notifications/configs

Required role: archive-content-manager

The configuration object takes these keys:

{
  "name": "Ingest failures to the DMS",
  "eventType": "ingest_failed",
  "actionType": "WEBHOOK",
  "enabled": true,
  "configuration": {
    "destination_url": "https://dms.example.com/hooks/archive",
    "headers": [
      { "headerKey": "X-Api-Key", "headerValue": "example-key" }
    ],
    "notification_template": "{\"event\": \"${name}\", \"package\": \"${packageId}\", \"message\": \"${message}\"}"
  }
}

Response: 200 OK with the NotificationConfig.

• 400 with REQUIRED_FIELD: notification_template, or the destination that the channel needs, is missing.

• 400 with INVALID_VALUE: the configuration has a setting of another channel, the destination_url isn't allowed, or the template uses a variable that isn't available.

• 400 with INVALID_FORMAT: the template isn't valid FreeMarker.

• 400 with UNSUPPORTED_VALUE: event_severity isn't low, moderate, or severe.

Update a notification configuration

Replaces the configuration with the body that you send. The body has the same fields as Create a notification configuration, so send all of them.

PUT /v2/notifications/configs/{configId}

Required role: archive-content-manager

Response: 200 OK with the updated NotificationConfig.

• 404: there's no notification configuration with this ID.

• The 400 errors of Create a notification configuration.

Delete a notification configuration

DELETE /v2/notifications/configs/{configId}

Required role: archive-content-manager

Response: 204 No Content. The archive stops sending this notification.

• 404: there's no notification configuration with this ID.

Schemas

NotificationConfig

NotificationConfigList