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!
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 endsjob.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 informations.
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"
}
}
}
}
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 25 days ago