Page Comparison

...

...

Assuming a conference has been recorded, and the archiving feature is enabled on the platform, an archive is created:

1. While being processed, the archive transitions through several internal states that mark steps in creating the archive (PROCESSING, ARTIFACT_GATHERING_COMPLETE, PACKING). In these states, the compressed file is not yet available, and can not yet be downloaded via the download archive endpoint.

2. Once all data has been aggregated, and the zip finalized, the status transitions to AVAILABLE. Now the archive can be downloaded via the API.

3. If there have been any failures in the process, the status is set to FAILED, and the error field describes the failure.

4. When the abandon archive endpoint has been called, the archive is scheduled for expiration. The status changes to ABANDONED. In the expiration period (which defaults to 3 days), the archive file can still be downloaded via the download archive endpoint.

5. After the expiration period has passed, the archive record transitions to the EXPIRED status and the file can no longer be downloaded via the download archive endpoint. The file is deleted from the flexperto platform.

When are archives deleted?

...

{
    "data": {
        "archive_id": "abc123",
        "archive_subject": {
            "conference_id": "xzy789",
            "meta": {/* flexperto conference data */}
        }
    },
    "meta": {
        "audience": "*",
        "tenant": "mycompany",
        "topic": "communication.archives.archive.available"
    }
}

Step 2: Register the webhook. Replace {api-key} with your API token, and {your-callback-url} with the previously exposed endpoint, e.g. https://internal.mycompany.de/callbacks/archive.

curl '{baseurl}/api/v2/communication/notificationssubscriptions/notificationssubscriptions/webhook' \
    -X POST \
    -H 'api-key: {api-key}' \
    -H 'Content-Type: application/json' \
    -d '{"topic": "communciation.archives.archive.available", "audience": "*", "url": "{your-callback-url}"}'

Step 3: On receiving a notification for an available archive, extract the archiveId from response.body.data.archive_id and the conferenceId from response.body.data.archive_subject.conference_id. You will need both later.

...

Step 4: We recommend persisting the archive record in your database of choice for an easier association between archive files, archive records, and your own compliance business processes. At the very least, persist the conferenceId, archiveId and sha256CheckSum fields.

Webhooks

The flexperto platform provides Webhooks in order to ease implementation of integrations as well as to provide close-to-realtime data exchange between the flexperto platform and your systems. In order to receive Webhooks, a Subscription has to be created. You can do so via:

curl '{baseurl}/communication/subscriptions/subscriptions/webhook' \
    -X POST \
    -H 'api-key: {api-key}' \
    -H 'Content-Type: application/json' \
    -d '{"topic": "communication.conferences.conference.close", "url": "{your-callback-url}"}'

Once a Subscription has been created, you will receive HTTP Callbacks at the url you have specified. The API-Documentation of your tenant ({baseurl}/api/v2/spec) lists the available topics for subscription under the “create Subscription” endpoints request specification.

Subscriptions can only be managed by administrators of a tenant, and are not account scoped (read as administrators can manage subscriptions of other administrators of the same tenant).

There are certain guarantees and contracts which come in line with providing and consuming Webhooks. These are:

Payload

Webhooks will always be delivered with an HTTPs POST request to your endpoint. The Payload will always be of Content-Type: application/json. The payload relating to a topic is documented on the API-Documentation of your tenant ({baseurl}/api/v2/spec). Scrolling down the page, the Models section should contain a model that relates to the topic (searching for NotificationPayload should navigate your browser to the section right away). Generally Webhook payloads at flexperto are permissive. There might be additional properties submitted, which are not documented on the payload type. flexperto neither guarantees their existence for every payload submitted, nor guarantees the type of these properties. For those properties listed, and which are marked as required on the specification, flexperto guarantees that they will always be present, and that their value will always be of the specified type. For those properties that are listed but not required as part of the specification, flexperto does not guarantee their presence, but if present, guarantees their value type.

Targets

Webhooks will only be delivered via TLS. Non https endpoints will either not be accepted or upon registration, or Webhooks will not be delivered. The url you provide must be DNS resolvable. The DNS resolved IP must not be a IANA IPv4 Special-Purpose Address (or IPv6 equivalent) or delivery will fail.

Delivery

When you receive a Webhook, you must respond with a status code that is greater than 199 and smaller than 399 (199 < statusCode < 399). A Webhook has to be responded to within 3 seconds. If any if these conditions are not given, flexperto will perform another delivery attempt. flexperto will perform up to 4 delivery attempts with an exponential backoff of 100ms. Therefore flexperto provides an at-least-once delivery guarantee (within 4 attempts of course). Flexperto does not provide an up-to-once guarantee. This means that in rare cases it is possilbe for you to receive the same webhook twice. Therefore please ensure that your implementation is idempotent. Flexperto performs delivery concurrently. It is possible that you receive multiple webhooks at the same time. Therefore please aim for your callback implementation to be atomic. Flexperto does not provide in-sequence/in-order guarantees. It is possible that you receive webhooks out of order (read as a failing delivery attempt, does not pause other deliveries). Continuously failing Webhooks will not cause flexperto to pause your subscription, but flexperto will be alerted about such cases and might approach you for verification. While statusCode 302/301 are accepted as a response callback, flexperto will not follow the redirects.

Reports

flexperto does maintain a backlog of the 50 latest delivery attempts of your subscription in the form of Reports. If you are observing unexpected retries or not receiving Webhooks at all, it is worth to take a look at the reports of your subscription. You can obtain them via

curl '{baseurl}/communication/subscriptions/subscriptions/{subscriptionId}/reports' \
    -X GET \
    -H 'api-key: {api-key}'

Security

Beyond of requiring TLS, flexperto does not provide an authentication mechanism for payload delivery between the flexperto platform and your systems. We therefore strongly recommend to implement one or all of these security mechanisms:

• Add a secret to the callback URL. Do not use URLs like my-site.com/callbacks/flexperto as they can be guessed easily. Instead embed a non-guessable path parameter (eg. my-site.com/callbacks/flexperto/F40mfum7pZC8DtdgGOYSijx26blP0HLs) for you to challenge

• Rotate the secret of the callback URL regularly. Using the API you can easily create a new subscription with the same topic but a different embedded path-parameter. Use this technique to regularly change the secret (be advised though that when you delete the old subscription, and there are still webhooks in-flight, those will be re-delivered upon failure up to 3 times anyways).

• Only allow requests originating from flexperto IP-Addresses. These are listed as part of the flexperto system requirements.

Linking to Expert Profiles

...