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:

• Insert API
• Replace API
• Change Metadata user interface

Webhook configuration

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

• Label: Name of the webhook
• Token: Token used for authentication with the external system (e.g. docuteam feeder token to send events to feeder using the Event API)
• Target URL: Endpoint to which to event is sent (e.g. http://feeder.docuteam.ch)
• Authentication option: Defines how box authenticates with the external system (currently the only possible value is feeder)
• 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 (currently additional metadata is only supported for metadata resources where the literal and the docuteam/vocab category are stored in the same resource.
• 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",
}

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