Webhooks

Time-to-live

If the consumer is down, events will be stored for one day (86400 seconds).

Error handling

Depending on the HTTP response codes from the consumer the following actions will be taken

State	Action	Comment

State	Action	Comment
<connection problems>	Retry	With exponential back-off (powers of 2)
HTTP code [200,299]	Success
HTTP codes [300,399] + 410	Abort web hook
HTTP codes [400,599] - 410	Retry	With exponential back-off (powers of 2)
Unknown HTTP code	Retry	With exponential back-off (powers of 2)

Formats

The following two formats are supported

Format	Description	Since

Format	Description	Since
Xml	Outputs in XML using a Premis event V2
XmlPremisV3	Outputs in XML using a Premis event V3 https://www.loc.gov/standards/premis/v3/index.htmland includes the https://mediahaven.atlassian.net/wiki/spaces/CS/pages/4058742786.	`24.1`

Example for XmlPremisV3

<?xml version="1.0" encoding="UTF-8"?>
<events>
    <premis:event xmlns:premis="http://www.loc.gov/premis/v3">
        <premis:eventIdentifier>
            <premis:eventIdentifierType>MEDIAHAVEN_EVENT</premis:eventIdentifierType>
            <premis:eventIdentifierValue>116729</premis:eventIdentifierValue>
        </premis:eventIdentifier>
        <premis:eventType>RECORDS.UPDATE</premis:eventType>
        <premis:eventDateTime>2023-11-09T17:28:25.955Z</premis:eventDateTime>
        <premis:eventDetailInformation>
            <premis:eventDetail/>
            <premis:eventDetailExtension>
                <mhs:Difference xmlns:mhs="https://zeticon.mediahaven.com/metadata/24.1/mhs/">
                    <mhs:MetadataFieldChange>
                        <mhs:DottedKey>Descriptive.Keywords</mhs:DottedKey>
                        <mhs:ValueBefore>
                            <mh:Keyword xmlns:mh="https://zeticon.mediahaven.com/metadata/24.1/mh/">test</mh:Keyword>
                        </mhs:ValueBefore>
                        <mhs:ValueAfter>
                            <mh:Keyword xmlns:mh="https://zeticon.mediahaven.com/metadata/24.1/mh/">test</mh:Keyword>
                            <mh:Keyword xmlns:mh="https://zeticon.mediahaven.com/metadata/24.1/mh/">Webhook!
                            </mh:Keyword>
                        </mhs:ValueAfter>
                    </mhs:MetadataFieldChange>
                </mhs:Difference>
            </premis:eventDetailExtension>
        </premis:eventDetailInformation>
        <premis:eventOutcomeInformation>
            <premis:eventOutcome>OK</premis:eventOutcome>
        </premis:eventOutcomeInformation>
        <premis:linkingAgentIdentifier>
            <premis:linkingAgentIdentifierType>MEDIAHAVEN_USER</premis:linkingAgentIdentifierType>
            <premis:linkingAgentIdentifierValue>310a81e3-4cd2-4564-a5fb-0071785c1c8e
            </premis:linkingAgentIdentifierValue>
        </premis:linkingAgentIdentifier>
        <premis:linkingObjectIdentifier>
            <premis:linkingObjectIdentifierType>MEDIAHAVEN_ID</premis:linkingObjectIdentifierType>
            <premis:linkingObjectIdentifierValue>
                5ba7d9cd7b23494e89d46e0dbb4cc3c5fc188e7f6f7f4c159ae1794d02a65f4f98617eb0373243b9aed9d906c40ae18f
            </premis:linkingObjectIdentifierValue>
        </premis:linkingObjectIdentifier>
    </premis:event>
</events>

Example format Xml (default)

<?xml version="1.0" encoding="UTF-8"?>
<events>
    <premis:event xmlns:premis="info:lc/xmlns/premis-v2">
        <premis:eventIdentifier>
            <premis:eventIdentifierType>MEDIAHAVEN_EVENT</premis:eventIdentifierType>
            <premis:eventIdentifierValue>116945</premis:eventIdentifierValue>
        </premis:eventIdentifier>
        <premis:eventType>RECORDS.UPDATE</premis:eventType>
        <premis:eventDateTime>2023-11-09T17:42:59.857Z</premis:eventDateTime>
        <premis:eventDetail/>
        <premis:eventOutcomeInformation>
            <premis:eventOutcome>OK</premis:eventOutcome>
        </premis:eventOutcomeInformation>
        <premis:linkingAgentIdentifier>
            <premis:linkingAgentIdentifierType>MEDIAHAVEN_USER</premis:linkingAgentIdentifierType>
            <premis:linkingAgentIdentifierValue>310a81e3-4cd2-4564-a5fb-0071785c1c8e
            </premis:linkingAgentIdentifierValue>
        </premis:linkingAgentIdentifier>
        <premis:linkingObjectIdentifier>
            <premis:linkingObjectIdentifierType>MEDIAHAVEN_ID</premis:linkingObjectIdentifierType>
            <premis:linkingObjectIdentifierValue>
                5ba7d9cd7b23494e89d46e0dbb4cc3c5fc188e7f6f7f4c159ae1794d02a65f4f98617eb0373243b9aed9d906c40ae18f
            </premis:linkingObjectIdentifierValue>
        </premis:linkingObjectIdentifier>
    </premis:event>
</events>

Event Types

Depending on the user's functions, webhooks can return two types of events. Each event includes the fully qualified event type, such as RECORDS.FLOW.ARCHIVED or USERS.FLOW.ROLES.

Premis events

Webhooks return premis events of records to which the user has read access. The event name always start with prefix RECORDS. The different event types are documented here https://mediahaven.atlassian.net/wiki/spaces/CS/pages/1490485332

Audit events

If the user has the function ADMIN_EDIT_ALL_ORGANISATIONS, https://mediahaven.atlassian.net/wiki/spaces/CS/pages/4400775176 from other concepts are also included.

Premis Event Links

The links in a premis event have of the two following formats

MediaObjectId (64 characters)
FragmentId (96 characters)

Variants

When the link is a MediaObjectId the event pertains to all fragments of the record
When the link a FragmentId the event pertains to only this specific fragments
Certain events such deleting the entire record will emit a DELETE event for each fragment with its own FragmentId

Tip

When requesting the events in JSON format you are guaranteed to always have the property FragmentId in addition to the Links whereas in the XML format only the links viapremis_event:linkingObjectIdentifier are present

Filters

When registering a webhook, you can define a filter to specify that only events of certain (sub) event types or (sub) record types should be received. Wildcards at the end are allowed. For example, the following webhook will only return update events for records with main record type Media:

"Filter": {
  "RecordTypes: ["Media", "Media.*"],
  "EventTypes": ["RECORDS.UPDATE", "RECORDS.UPDATE.*"]
}

If a user with the ADMIN_EDIT_ALL_ORGANISATIONS function only wants to receive premis events of records, the following filter can be applied:

"Filter": {
  "EventTypes": ["RECORDS.*"]
}

Permissions change

When the permissions of a record change in such manner the web hook user gains or losses the read right, in a narrow period around this transition events could be missed.

As such the UPDATE event which removes or adds the read right of the web hook user, may or may be not received by the web hook user.