Webhooks

docuteam box offers the option to configure webhooks if certain operations changing digital objects or their metadata happen in box. Webhooks will send POST request to other systems (e.g. docuteam feeder) containing JSON event data about changes to data in docuteam box.

List of operations

Webhooks can be configured for the following operations:

• Append object (API)
• Change Record Resource metadata (API)
• Change Record Resource metadata (UI)
• Delete object (API)
• Insert object (API)
• Replace object (API)

Webhook configuration

When creating or changing a webhook the following fields can be filled out:

• Label: Name of the webhook
• Target URL: Endpoint to which the event is sent (e.g. http://feeder.docuteam.ch)
• Token: Token used for authentication with the external system (e.g. docuteam feeder token to send events to feeder using the Event API)
• Operation: box operation which will activate the webhook

Additional metadata

• Optionally it is possible to add descriptive RDF metadata from the record resources to the event data by adding one or multiple additional metadata elements:
• Field label: Label of the json field in the event where the additional metadata is stored
• Predicate: Select a Matterhorn RDF predicate from the list of predicates currently used in Fedora (additional metadata is only supported for metadata resources where the literal and the docuteam/vocab category are part of the Record Resource that trigger the event).
• Include previous values: By default, the event will contain the value of the metadata element after the operation. The json field will be named field_label_is. Optionally you can also add the value before the operation, which will be stored in field_label_was. When creating a webhook for the insert operation, the old value will always be empty. When creating a webhook for the replace operation, old and new value will be identical.
• Insert multiple values: In case the metadata element occurs multiple times (or the data sent to the box operation contains multiple record resources), by default only the first value is added to the webhook. By activating this option, it is possible to add multiple values as a JSON array.

Example when using the field label unit_title:

{
    "unit_title_was" => "Old title",
    "unit_title_is" => "New title"
}

Event structure

The event structure depends on the type of operation:

Insert event

{
  "source": "#box base uri",
  "event_type": "box insert operation",
  "api_key_name": "#box authentication name (not the token) with which the request was executed",
  "root_node_pid": "#PID assigned to the root folder of the SIP",
  "sip_name": "#Name of the root folder of the SIP"
}

Replace operation

{
  "source": "#box base uri",
  "event_type": "box replace operation",
  "api_key_name": "#box authentication name (not the token) with which the request was executed",
  "pid": "#PID assigned to the file which was replaced",
  "file_name": "#Name of the new file"
}

Change Metadata operation

{
  "source": "#box base uri",
  "event_type": "box change metadata interface",
  "box_user_name": "#user name of the box user which changed the metadata",
  "pid": "#PID assigned to the Record Resource whose metadata was changed",
}

{
  "source": "#box base uri",
  "event_type": "box change metadata API",
  "box_user_name": "#user name of the box user which changed the metadata",
  "pid": "#PID assigned to the Record Resource whose metadata was changed",
}

Append Metadata operation

{ 
  "source": "#box base uri#",
  "event_type": "box append operation", 
  "box_api_key": "#box authentication name (not the token) with which the request was executed#", 
  "append_position_pid": "#PID where the data was appended to#",
  "root_node_pid": "#PID assigned to the root folder / root file which was appended"
}