Webhooks

Webhooks are a powerful way for Webfuse to communicate with your application. They allow you to receive real-time notifications when specific events occur in your Space or company. This enables you to automate workflows and integrate with third-party services, among other things.

Webhook Types

There are two types of webhooks: Space Webhooks, and Company Webhooks. Space webhooks are specific to a Space and related Sessions (e.g., a Session was started). An example for a company webhook is when a new user is added to the company.

Create a Webhook

Webhooks can be created using the REST API or the Webfuse Studio.

See full list of available Space Webhook Categories and Company Webhook Categories.

Security

Webhooks can be secured by generating a Webhook secret key. The Webhook Secret Key is used to sign the payload of the webhook. The signature is generated using the HMAC-SHA256 algorithm.

Webhook Secret Key

The Webhook Secret Key is a unique key that is used to sign the payload of the webhook. It can be generated in the API section of Webfuse company settings in case of Company webhook or in the API section of Webfuse Space settings for your Space in case of Space webhook.

Payload Handling

JSON payloads: The payload dictionary is serialized as-is without any sorting when calculating the signature

Signature Header

The signature is sent in the webhook-signature header.

Verification

To verify the webhook signature, recreate the HMAC-SHA256 signature using your webhook secret key and the webhook event payload object, then compare it with the signature in the header.

Payload Format

Webhooks are sent as HTTP POST requests to the URL you specify. The payload is a JSON object that contains information about the event that triggered the webhook. All webhooks requests include the User-Agent header with the value webfuse-webhooks/1.0. The request is compressed with gzip.

The payload format is as follows:

{
    "category": "space.session.started",
    "created_at": "2025-02-07T17:06:51.197164+00:00",
    "data": {
        ...
    },
    "sequence_id": 1
}

category - The category of the event that triggered the webhook.
created_at - The timestamp when the event occurred in ISO 8601 format.
data - The data associated with the event.
sequence_id - The sequence ID of the event. Used to establish the order of events and detect duplicates.

Webhook Events Lifecycle

When a webhook is triggered, Webfuse immediately sends an HTTP POST request to the URL you specify. If the request fails, Webfuse will retry one more time immediately and then again after 5 minutes, 10 minutes, 15 minutes, 30 minutes, 1 hour, 4 hours, 8 hours, 12 hours. After that, Webfuse will retry every 24 hours for up to 7 days.

After 300 failed requests, Webfuse will stop sending requests to the URL and the webhook will be disabled. Company and Space administrators will be notified about it via email.

The webhook event is considered successfully delivered if the HTTP response code is 2xx and was received within 5 seconds.

Outbound IP Addresses

Webhooks are delivered by the Webfuse backend, not by the regional server your Sessions run on. Selecting, for example, the ca-east region for Sessions does not make webhooks originate from Canada.

If your firewall only accepts inbound traffic from specific addresses, you can use the /v2/servers/ endpoint to check the public IP addresses of our servers, and whitelist:

the IP addresses of the eu-de entry (Germany, Nuremberg) from https://webfuse.com/v2/servers/ if you are using webfuse.com, since the backend runs on our primary cluster there
the IP addresses of the Dashboard node entry from https://us.webfuse.com/v2/servers/ if you are using us.webfuse.com

Space Webhook Categories

space.session.started

{
    "category": "space.session.started",
    "created_at": "2025-02-07T17:06:51.197164+00:00",
    "data": {
        "duration": null,
        "first_member": null,
        "link": "https://webfuse.com/sZQM9askvSCqSa2I2cJfQJujA",
        "participant_count": 0,
        "pin": null,
        "queue_duration": null,
        "session_id": "sZQM9askvSCqSa2I2cJfQJujA",
        "space_id": 23,
        "started_at": "2025-02-07T17:06:51.184169+00:00"
    },
    "sequence_id": 40
}

space.session.audit_logs_created

{
    "category": "space.session.audit_logs_created",
    "created_at": "2025-02-13T15:48:14.189387+00:00",
    "data": [
        {
            "details": {
                "created_from": "console",
                "ip": null,
                "options": {...},
                "server_region": "",
                "session_id": "sXToqARIEAYT8encxvNqlSFIw",
                "start_url": ""
            },
            "time": "2025-02-13T14:05:16.491727",
            "type": "session_created"
        },

        ...],
    "sequence_id": 50
}

space.session.client_log_added

This event is triggered when a client log is added to the audit logs of a session. For more information about client log, see the Audit Log page.

{
    "category": "space.session.client_log_added",
    "created_at": "2025-02-13T16:54:20.685647+00:00",
    "data": {
        "space_id": 23,
        ...
    },
    "sequence_id": 52
}

space.session.ended

This event is triggered when a session ends.

{
    "category": "space.session.ended",
    "created_at": "2025-02-07T17:16:51.197164+00:00",
    "data": {
        "duration": 600,
        "first_member": null,
        "link": "https://webfuse.com/sZQM9askvSCqSa2I2cJfQJujA",
        "participant_count": 2,
        "pin": null,
        "queue_duration": null,
        "session_id": "sZQM9askvSCqSa2I2cJfQJujA",
        "space_id": 23,
        "started_at": "2025-02-07T17:06:51.184169+00:00"
    },
    "sequence_id": 53
}

space.session.queued

This event is triggered when an assisted session is created and placed in the queue. Only applies to assisted spaces where a PIN is generated for the session.

{
    "category": "space.session.queued",
    "created_at": "2025-02-07T17:06:51.197164+00:00",
    "data": {
        "duration": null,
        "first_member": null,
        "link": "https://webfuse.com/sZQM9askvSCqSa2I2cJfQJujA",
        "participant_count": 0,
        "pin": "1234",
        "queue_duration": null,
        "session_id": "sZQM9askvSCqSa2I2cJfQJujA",
        "space_id": 23,
        "started_at": "2025-02-07T17:06:51.184169+00:00"
    },
    "sequence_id": 54
}

space.session.screenshot

This event is triggered when a screenshot is taken during a session.

{
    "category": "space.session.screenshot",
    "created_at": "2025-02-07T17:10:00.000000+00:00",
    "data": {
        "session_id": "sZQM9askvSCqSa2I2cJfQJujA",
        "space_id": 23,
        "space_name": "My Space",
        "screenshot_url": "https://example.com/screenshot.png"
    },
    "sequence_id": 55
}

space.session.participant_joined

This event is triggered when a new participant joins a session and the participant count increases.

{
    "category": "space.session.participant_joined",
    "created_at": "2025-02-07T17:08:00.000000+00:00",
    "data": {
        "session_id": "sZQM9askvSCqSa2I2cJfQJujA",
        "space_id": 23,
        "space_name": "My Space",
        "participant_count": 2
    },
    "sequence_id": 56
}

space.session.participant_left

This event is triggered when a participant’s connection to a session ends, and identifies who left instead of reporting a count.

{
    "category": "space.session.participant_left",
    "created_at": "2025-02-07T17:12:00.000000+00:00",
    "data": {
        "session_id": "sZQM9askvSCqSa2I2cJfQJujA",
        "space_id": 23,
        "space_name": "My Space",
        "email": "alice@example.com",
        "name": "Alice",
        "client_index": 1,
        "user_id": 42,
        "is_leader": false
    },
    "sequence_id": 57
}

email, name and user_id are null for participants who joined without identifying themselves.

The event tracks connections, not people, so do not treat it as the inverse of space.session.participant_joined:

A page reload or a dropped network connection fires participant_left. The participant reconnecting afterwards usually fires no participant_joined, because that event only fires when the session’s participant count reaches a new maximum. Deriving current occupancy by counting joins minus leaves will therefore drift.
Opening a session in a second connection fires participant_left for the connection it replaces, even though the participant is still present.
Session recorders are excluded — their departure is reported as space.recording.ended instead.

Use client_index to correlate events belonging to the same connection.

space.session.invitation

This event is triggered when a session invitation is sent to one or more email addresses.

{
    "category": "space.session.invitation",
    "created_at": "2025-02-07T17:07:00.000000+00:00",
    "data": {
        "session_id": "sZQM9askvSCqSa2I2cJfQJujA",
        "space_id": 23,
        "space_name": "My Space",
        "invitees": ["alice@example.com", "bob@example.com"]
    },
    "sequence_id": 59
}

space.session.recording_uploaded

download_url is the URL to download the recording. The URL is valid for 1 hour.

{
    "category": "space.session.recording_uploaded",
    "created_at": "2025-02-13T16:54:20.685647+00:00",
    "data": {
        "filename": "recording.mp4",
        "download_url": "https://example.com/recording.mp4",
        "session_id": "sXToqARIEAYT8encxvNqlSFIw",
        "space_id": 23,
        "space_name": "My Space"
    },
    "sequence_id": 51
}

space.recording.started

This event is triggered when recording starts for a session.

{
    "category": "space.recording.started",
    "created_at": "2025-02-07T17:07:00.000000+00:00",
    "data": {
        "session_id": "sZQM9askvSCqSa2I2cJfQJujA",
        "space_id": 23,
        "space_name": "My Space"
    },
    "sequence_id": 57
}

space.recording.ended

This event is triggered when recording ends for a session.

{
    "category": "space.recording.ended",
    "created_at": "2025-02-07T17:15:00.000000+00:00",
    "data": {
        "session_id": "sZQM9askvSCqSa2I2cJfQJujA",
        "space_id": 23,
        "space_name": "My Space"
    },
    "sequence_id": 58
}

Company Webhook Categories

company.user_created

{
    "category": "company.user_created",
    "created_at": "2025-02-13T16:54:20.685647+00:00",
    "data": {
        "avatar_url": null,
        "email": "amy@webfuse.com",
        "id": 2,
        "initials": "AP",
        "language": "en",
        "last_login": null,
        "name": "Amy Pond",
        "role": "user",
        "time_zone": "UTC"
    },
    "sequence_id": 51
}

company.agent.password_reset

This event is triggered when a user resets their password.

{
    "category": "company.agent.password_reset",
    "created_at": "2025-02-13T16:54:20.685647+00:00",
    "data": {
        "avatar_url": null,
        "email": "amy@webfuse.com",
        "id": 2,
        "initials": "AP",
        "language": "en",
        "last_login": null,
        "name": "Amy Pond",
        "role": "user",
        "time_zone": "UTC"
    },
    "sequence_id": 52
}

company.agent.account_activation

This event is triggered when a user account is activated.

{
    "category": "company.agent.account_activation",
    "created_at": "2025-02-13T16:54:20.685647+00:00",
    "data": {
        "avatar_url": null,
        "email": "amy@webfuse.com",
        "id": 2,
        "initials": "AP",
        "language": "en",
        "last_login": null,
        "name": "Amy Pond",
        "role": "user",
        "time_zone": "UTC"
    },
    "sequence_id": 53
}