Webhooks allow a client of Claap to be automatically notified of key events relating to their workspace and recordings, thereby enabling the creation of custom workflows and automations with 3rd party apps.
Webhook setup
Please contact support@claap.io to register your webhook.
In your request, please provide:
The URL you would like to connect
The event(s) you would like to register to
As part of the registration, a webhook identifier and secret will be communicated to you.
Entities
Schemas of entities shared by API endpoints or webhooks are described in the following sections.
Recording
A recording represents a successfully transcoded and analyzed result of a video clip or meeting.
actionItems (array of objects, required): a sequence of action items analyzed from the recording content. Each item is made of a markdown description and an isChecked boolean telling whether the action has been marked as completed.
items(array of objects, required):description(string, required): action description as markdownisChecked(boolean, required): true if the action has been validated
langIso2(string, required): language of the items group
channel(object, optional): the channel the recording belongs to if anyid(string, required)name(string, required)
companies(array of objects, required): external companies involved in the meetingid(string, required)name(string, required)
createdAt(string, required): recording creating time in ISO format. Note this is when the recording was initiated, not when it became ready for consumption. Often, this coincides with the time the related meeting started.deal(object, optional): the deal attached to the meeting, if anyid(string, required)name(string, optional)
durationSeconds(number, required): duration of the recording video in seconds.insightTemplates(array of objects, required)insights(array of objects, required)langIso2(string, required)sections(array of objects, required)title(string, required)description(string, required): as markdown.
templateTitle(string, required)
labels(array of strings, required)id(string, required): recording identifierkeyTakeaways(array of objects, required)langIso2(string, required)text(string, required)
meeting(object, optional): the meeting related to the recording if anyparticipants(array of objects, required): a collection of persons possibly attending the meeting, participants or organizers.attended(boolean, required): if the participant actually took part to the meetingemail(string, optional)id(string, optional)name(string, optional)
outlines(array of objects, required)langIso2(string, required)text(string, required)
recorder(object, required): the person recording the clip or meetingattended(boolean, required): true if the recorder attended the meetingemail(string, required)id(string, required)name(string, required)
transcripts(array, required): the list of all transcript, made of the native transcript and requested translationsisActive(boolean, optional): true if this transcript is the default one selected for the recording.isTranscript(boolean, optional): true if this is the native transcriptlangIso2(string, optional): the transcript language codetextUrl(string, required): the URL to the transcript text representation, valid for 24 hours.url(string, required): the URL to the transcript JSON file, valid for 24 hours.
thumbnailUrl(string, required): link to the thumbnail picture illustrating this recordingtitle(string, optional): recording titleurl(string, required): recording page URL in claap web application.video(object, required)url(string, required): recording video URL, valid for 24 hours.
Transcript
A JSON transcript is available at the URL available in transcripts[].url
Timecode are relative to the transcribed audio timeline, in seconds, starting at zero.
language(string, optional): iso-2 code of the “main” language of the transcriptsegments(array, required): the array of speaking segments, each attached to a single speakerendedAt(number, required): segment end timecode.languageCode(string, optional): iso-2 code of the “main” language of the segmentspeaker(string, optional): arbitrary speaker identifierstartedAt(number, required): segment start timecodetext(string, required): segment transcriptionwords(array, optional): sequence of words composing the segmentendedAt(number, required): word end timecodestartedAt(number, required): word start timecodeword(string, required): word transcription
Webhooks
Webhooks are registered in a workspace and fired when the following events take place in the workspace:
recording_added: a new recording is availablerecording_updated: a recording was updated
See the Events section below for more details on these events.
When one of these events takes place, the client endpoint receives the payload as a POST HTTPS request, in JSON format.
The client is expected to answer with a 200 status code within 5 seconds. Failing to do that, several retries will be triggered within a 5-minute span, before being discarded.
The following headers are set in the request:
X-Claap-Webhook-Id: the webhook identifier.X-Claap-Webhook-Secret: a secret key bound to the webhook, which can be used to check the request comes from Claap.
Event structure
Webhook payloads are structured as JSON objects like:
{
"eventId": "eeghaiCh8Chaikusa5che",
"event": {
"type": "recording_added",
"recording": {
... <Recording> payload
}
}
}Where event.type identifies the kind of event being received and eventId identifies this particular instance of webhook invocation. eventId is shared by all retries of a same invocation.
Events
recording_added
The recording_added event type is emitted when a new recording, from a clip or a meeting, is made available to workspace members.
Private recordings are excluded.
A recording is available once it is transcoded, transcribed and analyzed. Its payload includes recording metadata, an outline, insights, as well as links to various recording-specific resources (transcripts, video file). When the recording is a meeting recording, the payload will also contain, if relevant, information about participants, deal, and company.
recording_updated
The recording_updated event type is emitted when some properties of a recording are updated. Whenever one of the following properties in a recording changes, this event will be fired:
Channel
Label
Attached Deal
Attached Company
Insights template
Private recordings are excluded.
The payload includes the complete Recording entity, similar to the payload sent for a recording_added event.
Example JSON Payload
Below is a JSON file containing an example of the payload received for a recording_added event:
API
Claap REST-like API is exposed on https://api.claap.io/api via HTTPS.
It is currently minimalistic and allows webhook to be manually triggered, which can be useful when integrating them.
Response body will always be a JSON object.
On success, it will be like:
{
"ok": true,
"data": {
... optional additional attributes depending on the call ...
}
}Error responses look like:
{
"ok": false,
"error": "some_error_code",
"errMessage": "an optional human readable error message adding some context"
}
Endpoints
POST v1/webhook/${webhookId}/trigger
Manually trigger a webhook
The caller must authentify themselves by passing the webhook secret in X-Claap-Webhook-Secret header.
webhookIdis the identifier of the webhook to trigger
The payload is a JSON object, which content depends on the event being triggered:
recording_added:{
"type": "recording_added",
"recordingId": "fahpechuF8qu"
}
recording_updated:{
"type": "recording_updated",
"recordingId": "fahpechuF8qu"
}
The endpoint answers with 200 on success, with no additional attributes.