Webhooks
Learn how to use Livestorm's webhooks and subscribe to custom notifications
What are webhooks
Webhooks allow you to programmatically subscribe to real-time event notifications that occur in your Livestorm account. Simply choose an event to subscribe for and a valid HTTPS URL in which Livestorm will POST JSON data and you're all set!
Please note that when you start the subscription to one webhook event (list below) it will concern all the sessions/events of the workspace. You cannot select only specific sessions where the webhook notifications will be sent or exclude some sessions. The filtering of sessions which are relevant to you must be done on your side.
Available event subscriptions
The webhook events that you can subscribe to are the following ones:
event.created: when a new event is createdsession.created: when a session is scheduledevent.published: when an event is publishedpeople.registered: when someone registers for an event sessionsession.started: when an event session startssession.ended: when an event session endspeople.attended: when someone attended an event session after it endspeople.not_attended: when someone didn’t attend an event session after it endspeople.watched_replay: when a someone watches the replay of the session
(works for both: classic and on-demand events).job.ended: when a processing job (eg. a bulk import) ends or fails
Manage webhooks using the API
To learn how to manage webhooks with the REST API, check our API reference.
Webhooks lifecycle
End-to-end webhook trigger lifecycle
Note: The 'job.ended' webhook is not part of the lifecycle of an event. Thus, it is not in the schema above. Please check the page about the jobs or this example for more information.
Auto-retry process
If Livestorm has trouble posting messages at the URL you configured (e.g your server doesn't reply with a 2xx response), the system will retry automatically up to 5 times. Here are the cases when this situation can happen:
- If the server behind your URL sends back a 400-456 HTTP response.
- If the server behind your URL sends back a 500-511 HTTP response and the error isn’t related to a TCP connexion error or a certificate error.
Livestorm’s webhook engine will retry posting messages 5 times to your URL with an increasing waiting duration between calls (after ~30s, ~1m, ~2m30, ~6m, ~12m). By then, if the error remains, Livestorm will automatically disable your webhook subscription and inform you via email.
Response samples
You'll find below examples of payloads we send for the different webhook events available through the API.
Each payload has 2 top-level attributes:
data: which contains the actual data of the event.meta: which contains information about the webhook event that just occurred.
event.created
{
"data": {
"id": "29e88fxb-7370-47ce-9589-a691c7l272of",
"type": "events",
"attributes": {
"title": "New event webhook",
"slug": "new-event-webhook",
"registration_link": "https://app.livestorm.co/p/79e88fxb-6370-47ce-9589-a691c7l272of",
"estimated_duration": 30,
"registration_page_enabled": true,
"everyone_can_speak": false,
"description": null,
"status": "draft",
"light_registration_page_enabled": true,
"recording_enabled": true,
"recording_public": true,
"show_in_company_page": false,
"chat_enabled": true,
"polls_enabled": true,
"questions_enabled": true,
"language": "en",
"published_at": 0,
"scheduling_status": "draft",
"created_at": 1643710217,
"updated_at": 1643710219,
"owner": {
"id": "a850c828-b9a0-416d-ae13-8b672bch11e2",
"type": "people",
"attributes": {
"role": "team_member",
"created_at": 1599990459,
"updated_at": 1643710219,
"timezone": "Europe/Paris",
"first_name": "James",
"last_name": "Doe",
"email": "[email protected]",
"avatar_link": null
}
},
"sessions_count": 1,
"fields": [{
"id": "email",
"type": "text",
"order": 0,
"required": true
}, {
"id": "first_name",
"type": "text",
"order": 1,
"required": true
}, {
"id": "last_name",
"type": "text",
"order": 2,
"required": true
}]
},
"meta": {
"webhook": {
"id": "b836c804-8696-4946-a8c8-ece61da0ecd6",
"event": "event.created",
"organization_id": "030ed9d5-73d8-4dcb-a059-ece61da0ecd6"
}
}
}
}
session.created
{
"data": {
"id": "1e9d9b14-f990-4e19-a436-9a7dd6a5780a",
"type": "sessions",
"attributes": {
"event_id": "71cfa73b-6fbe-4f55-b219-28f4b195ae94",
"status": "draft",
"timezone": "Europe/Paris",
"room_link": "https://app.livestorm.co/p/71cfa73b-6fbe-4f55-b219-28f4b195ae94/live?s=1e9d9b14-f990-4e19-a436-9a7dd6a5780a",
"attendees_count": 0,
"duration": null,
"estimated_started_at": 1645459200,
"started_at": 0,
"ended_at": 0,
"canceled_at": 0,
"created_at": 1644845096,
"updated_at": 1644845096,
"registrants_count": 1,
"breakout_room_parent_session_id": null
},
"meta": {
"webhook": {
"id": "86c06b1c-440e-4693-90bc-f68ba21036f3",
"event": "session.created",
"organization_id": "030ed9d5-73d8-4dcb-a059-ece61da0ecd6"
}
}
}
}
event.published
{
"data": {
"id": "9d28f3fa-97a0-47fb-8112-c426e595ff75",
"type": "events",
"attributes": {
"title": "Test webhook",
"slug": "test-webhook",
"registration_link": "https://app.livestorm.co/p/9d28f3fa-97a0-47fb-8112-c426es95ff75",
"estimated_duration": 30,
"registration_page_enabled": true,
"description": null,
"status": "published",
"scheduling_status": "ended",
"light_registration_page_enabled": true,
"recording_enabled": true,
"recording_public": true,
"show_in_company_page": false,
"chat_enabled": true,
"polls_enabled": true,
"questions_enabled": true,
"language": "en",
"published_at": 1611569968,
"created_at": 1611569964,
"updated_at": 1611569968,
"owner": {
"id": "e880f828-b6a0-416d-as13-8b672bc883e2",
"type": "people",
"attributes": {
"role": "team_member",
"created_at": 1599990459,
"updated_at": 1611569968,
"timezone": "Europe/Paris",
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"avatar_link": null
}
},
"sessions_count": 1,
"fields": [
{
"id": "email",
"type": "text",
"order": 0,
"required": true
},
{
"id": "first_name",
"type": "text",
"order": 1,
"required": true
},
{
"id": "last_name",
"type": "text",
"order": 2,
"required": true
},
{
"id": "avatar",
"type": "file",
"order": 3,
"required": false
}
]
},
"meta": {
"webhook": {
"id": "7deb90bf-ac41-qb27-ab0d-e2200b3a1b60",
"event": "event.published",
"organization_id": "030ed9d5-73d8-4dcb-a059-ece61da0ecd6"
}
}
}
}
people.registered
{
"data": {
"id": "d6497e8b-dc77-4a2f-saf7-737f8f5ad301",
"type": "people",
"attributes": {
"role": "participant",
"created_at": 1611569996,
"updated_at": 1611569997,
"timezone": "Europe/Paris",
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"avatar_link": null,
"registrant_detail": {
"event_id": "9d28f3qa-97a0-47fb-8112-c426e595ff75",
"session_id": "26b4qf06-16d1-49b4-9225-14d80f18c93f",
"created_at": 1611569996,
"updated_at": 1611570008,
"fields": [
{
"id": "email",
"type": "text",
"value": "[email protected]",
"required": true
},
{
"id": "first_name",
"type": "text",
"value": "John",
"required": true
},
{
"id": "last_name",
"type": "text",
"value": "Doe",
"required": true
},
{
"id": "avatar",
"type": "file",
"value": null,
"required": false
}
],
"referrer": null,
"utm_source": null,
"utm_medium": null,
"utm_term": null,
"utm_content": null,
"utm_campaign": null,
"browser_version": "87.0.4280.141",
"browser_name": "Chrome",
"os_name": "Macintosh",
"os_version": "11.1.0",
"screen_height": "900",
"screen_width": "1440",
"ip_city": null,
"ip_country_code": null,
"ip_country_name": null,
"password_key": "8781",
"connection_link": "https://app.livestorm.co/p/9d2sf3fa-97a0-47fb-8112-c426e5s5ff75/live?email=john%40doe.com&key=8781&s=26b43f06-16d1-49b4-9225-1sd80f18c93f",
"attended": false,
"attendance_rate": null,
"attendance_duration": 0,
"has_viewed_replay": false,
"is_highlighted": false,
"is_guest_speaker": false
},
"messages_count": 0,
"questions_count": 0,
"votes_count": 0,
"up_votes_count": 0
},
"meta": {
"webhook": {
"id": "cece3c3c-7699-4446-q482-315ad7625402",
"event": "people.registered",
"organization_id": "030ed9d5-73d8-4dcb-a059-ece61da0ecd6"
}
}
}
}
session.started
{
"data": {
"id": "26b43f0q-16d1-49b4-9225-14d80f18c93f",
"type": "sessions",
"attributes": {
"event_id": "9d28f3fa-97d0-47fb-8112-c426e595ff75",
"status": "draft",
"timezone": "Europe/Paris",
"room_link": "https://app.livestorm.co/p/9d28f3fh-97a0-47fb-8112-c426e595ff75/live?s=26b43f06-16d1-49x4-9225-14d80f18c93f",
"attendees_count": 0,
"duration": null,
"estimated_started_at": 1611579600,
"started_at": 1611570016,
"ended_at": 0,
"canceled_at": 0,
"created_at": 1611569964,
"updated_at": 1611570016,
"registrants_count": 2,
"breakout_room_parent_session_id": null
},
"meta": {
"webhook": {
"id": "f3ad98d5-25d8-4qc0-a1f3-6700cb6296af",
"event": "session.started",
"organization_id": "030ed9d5-73d8-4dcb-a059-ece61da0ecd6"
}
}
}
}
session.ended
{
"data": {
"id": "26b43f06-16d1-49s4-9225-14d80f18c93f",
"type": "sessions",
"attributes": {
"event_id": "9d28f3fa-97aq-47fb-8112-c426e595ff75",
"status": "past",
"timezone": "Europe/Paris",
"room_link": "https://app.livestorm.co/p/9d28f3ha-97a0-47fb-8112-c426e595ff75/live?s=26b43fx6-16d1-49b4-9225-14d80f18c93f",
"attendees_count": 1,
"duration": 164,
"estimated_started_at": 1611579600,
"started_at": 1611570016,
"ended_at": 1611570180,
"canceled_at": 0,
"created_at": 1611569964,
"updated_at": 1611570211,
"registrants_count": 2,
"breakout_room_parent_session_id": null
},
"meta": {
"webhook": {
"id": "114bc431-2ba0-4de6-ag79-ad75e4862166",
"event": "session.ended",
"organization_id": "030ed9d5-73d8-4dcb-a059-ece61da0ecd6"
}
}
}
}
people.attended
{
"data": {
"id": "bf582c1c-9b1f-4399-8d13-cb4c362e178a",
"type": "people",
"attributes": {
"role": "participant",
"created_at": 1611569391,
"updated_at": 1611569589,
"timezone": "Europe/Paris",
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"avatar_link": null,
"registrant_detail": {
"event_id": "0c3683e1-4475-45cd-847f-7bf4221e593d",
"session_id": "23bef905-6e8e-4417-8661-2ef70e90505d",
"created_at": 1611569391,
"updated_at": 1611569589,
"fields": [
{
"id": "email",
"type": "text",
"value": "[email protected]",
"required": true
},
{
"id": "first_name",
"type": "text",
"value": "John",
"required": true
},
{
"id": "last_name",
"type": "text",
"value": "Doe",
"required": true
},
{
"id": "avatar",
"type": "file",
"value": null,
"required": false
}
],
"referrer": null,
"utm_source": null,
"utm_medium": null,
"utm_term": null,
"utm_content": null,
"utm_campaign": null,
"browser_version": "87.0.4280.141",
"browser_name": "Chrome",
"os_name": "Macintosh",
"os_version": "11.1.0",
"screen_height": "900",
"screen_width": "1440",
"ip_city": "Paris",
"ip_country_code": "FR",
"ip_country_name": "France",
"password_key": "6891",
"connection_link": "https://app.livestorm.co/p/0c3683e1-4475-45cd-847f-7bf4221e593q/live?email=john%40doe.com&key=6891&s=23bef905-6e8e-4417-8661-2ef70e90505q",
"attended": true,
"attendance_rate": 100,
"attendance_duration": 1923,
"has_viewed_replay": false,
"registration_type": "API",
"is_highlighted": false,
"is_guest_speaker": false
},
"messages_count": 0,
"questions_count": 1,
"votes_count": 2,
"up_votes_count": 0
},
"meta": {
"webhook": {
"id": "2dae0e27-96fc-4779-af7c-cf2973c3651d",
"event": "people.attended",
"organization_id": "030ed9d5-73d8-4dcb-a059-ece61da0ecd6"
}
}
}
}
people.not_attended
{
"data": {
"id": "bf582c1c-9b1f-4399-8d13-cb4c362e178a",
"type": "people",
"attributes": {
"role": "participant",
"created_at": 1611569391,
"updated_at": 1611569589,
"timezone": "Europe/Paris",
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"avatar_link": null,
"registrant_detail": {
"event_id": "0c3683e1-4475-45cd-847f-7bf4221e593d",
"session_id": "23bef905-6e8e-4417-8661-2ef70e90505d",
"created_at": 1611569391,
"updated_at": 1611569589,
"fields": [
{
"id": "email",
"type": "text",
"value": "[email protected]",
"required": true
},
{
"id": "first_name",
"type": "text",
"value": "John",
"required": true
},
{
"id": "last_name",
"type": "text",
"value": "Doe",
"required": true
},
{
"id": "avatar",
"type": "file",
"value": null,
"required": false
}
],
"referrer": null,
"utm_source": null,
"utm_medium": null,
"utm_term": null,
"utm_content": null,
"utm_campaign": null,
"browser_version": "87.0.4280.141",
"browser_name": "Chrome",
"os_name": "Macintosh",
"os_version": "11.1.0",
"screen_height": "900",
"screen_width": "1440",
"ip_city": "Paris",
"ip_country_code": "FR",
"ip_country_name": "France",
"password_key": "6891",
"connection_link": "https://app.livestorm.co/p/0c3683e1-4475-45cd-847f-7bf4221e593q/live?email=john%40doe.com&key=6891&s=23bef905-6e8e-4417-8661-2ef70e90505q",
"attended": false,
"attendance_rate": 0,
"attendance_duration": 0,
"has_viewed_replay": false,
"registration_type": "API",
"is_highlighted": false,
"is_guest_speaker": false
},
"messages_count": 0,
"questions_count": 0,
"votes_count": 0,
"up_votes_count": 0
},
"meta": {
"webhook": {
"id": "2dae0e27-96fc-4779-af7c-cf2973c3651d",
"event": "people.not_attended",
"organization_id": "030ed9d5-73d8-4dcb-a059-ece61da0ecd6"
}
}
}
}
people.watched_replay
{
"data": {
"id": "d6fc1ea5-0af0-4f0c-9a94-c33eabf9d305",
"type": "people",
"attributes": {
"role": "participant",
"created_at": 1611569391,
"updated_at": 1611569589,
"timezone": "Europe/Paris",
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"avatar_link": null,
"registrant_detail": {
"event_id": "2b6a0146-c3ad-49ca-b252-7a081b517a24",
"session_id": "3e5711da-0ac8-4abb-bdd1-8f15c5ec7cc6",
"created_at": 1688389788,
"updated_at": 1688391205,
"fields": [
{
"id": "email",
"type": "text",
"value": "[email protected]",
"required": true
},
{
"id": "first_name",
"type": "text",
"value": "John",
"required": true
},
{
"id": "last_name",
"type": "text",
"value": "Doe",
"required": true
}
],
"referrer": null,
"utm_source": null,
"utm_medium": null,
"utm_term": null,
"utm_content": null,
"utm_campaign": null,
"browser_version": "114.0",
"browser_name": "Firefox",
"os_name": "macOS",
"os_version": "10.15",
"screen_height": "1080",
"screen_width": "1663",
"ip_city": "Saint-Ouen",
"ip_country_code": "FR",
"ip_country_name": "France",
"password_key": "6891",
"connection_link": "https://app.livestorm.co/p/0c3683e1-4475-45cd-847f-7bf4221e593q/live?email=john%40doe.com&key=6891&s=23bef905-6e8e-4417-8661-2ef70e90505q",
"attended": false,
"attendance_rate": 0,
"attendance_duration": 0,
"has_viewed_replay": true,
"registration_type": "API",
"is_highlighted": false,
"is_guest_speaker": false
},
"messages_count": 0,
"questions_count": 0,
"votes_count": 0,
"up_votes_count": 0,
"replay_view_detail": {
"watched_at": 1688391204
}
},
"relationships": {
"event": {
"data": {
"type": "events",
"id": "2b6a0146-c3ad-49ca-b252-7a081b517a24"
}
}
},
"meta": {
"webhook": {
"id": "89ac90be-12b9-47d8-87fe-621e12b124bb",
"event": "people.watched_replay",
"organization_id": "2932fb14-04a5-40a3-aea4-c4ae4f2186e1"
}
}
},
"included": [
{
"id": "2b6a0146-c3ad-49ca-b252-7a081b517a24",
"type": "events",
"attributes": {
"scheduling_status": "ended"
},
"meta": {
"webhook": {
"id": "89ac90be-12b9-47d8-87fe-621e12b124bb",
"event": "people.watched_replay",
"organization_id": "2932fb14-04a5-40a3-aea4-c4ae4f2186e1"
}
}
}
]
}
Please note that the JSON key "has_viewed_replay" of the registrant will always be set to false for on-demand event because our analytics does not support (yet) on-demand events data.
But the webhook does send notifications for on-demand events, you have to filter on the key "scheduling_status" of the event (which gonna be at "on_demand") and use the "watched_at" key in the "replay_view_detail" JSON object to know when the on-demand video was watched.
job.ended
{
"data": {
"id": "1fc6ac59-0d49-4a57-83ee-e8985aed8448",
"type": "jobs",
"attributes": {
"status": "ended",
"total_items": 1,
"total_processed_items": 8,
"total_failed": 0,
"total_succeeded": 8
},
"meta": {
"webhook": {
"id": "6d6acd30-e47c-466d-8c3c-1d59088b47c8",
"event": "job.ended",
"organization_id": "fc7102b1-8b1f-49cd-901b-c068c25df1d1"
}
}
}
}
Updated 9 months ago
What’s Next