Documentation
✉️ Developer Newsletter💡 Feature Request📖 Help Center

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 created
  • session.created : when a session is scheduled
  • event.published : when an event is published
  • people.registered : when someone registers for an event session
  • session.started : when an event session starts
  • session.ended : when an event session ends
  • people.attended : when someone attended an event session after it ends
  • people.not_attended : when someone didn’t attend an event session after it ends
  • people.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

3431

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 about 1 year ago

What’s Next