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 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

👍

Manage webhooks using the API

To learn how to manage webhooks with the REST API, check our API reference.

Webhooks lifecycle

34313431

End-to-end webhook trigger lifecycle

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": false,
        "attendance_rate": 0,
        "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": "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,
        "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"
      }
    }
  }
}

What’s Next