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 Difference.	`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

The different event types are documented here Events
Web hooks always contain the fully qualified event type such as RECORDS.FLOW.ARCHIVED

Premis 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

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.