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

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.