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.

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",
        "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.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.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": {...},
    "sequence_id": 52
}

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
}