Webhooks

If your pricing plan allows API usage, you can register webhooks on the Integration page. Every webhook must be set with a valid URL and subscribed to at least one event.

Event format

When an event is triggered, we will send an HTTP POST request with a corresponding event data to each subscribed webhook. Request body is always a JSON-encoded object with the following structure:

{
  "sequence_id": "<integer>",
  "type": "<string>",
  "data": "<object>"
}

• sequence_id is a unique ID assigned to the event. Sequence ids start from a certain positive number and increase with each new event. This way you can restore the correct sequence of events if they get out of order.
• type is a string representing an event type.
• data contains a JSON object. The object structure depends on the event type (see below)

If we detect that an event cannot be delivered (for example, if the webhook URL is not available), we will try again after some delay. If the delivery doesn't succeed after a reasonable number of retries, the webhook will be automatically deactivated, and admin users will be notified via email.

Available events

Currently you can subscribe to the following events:

session.queued

Triggered when a session is placed in the queue

{
    "session_id": "<string>",
    "leader_link": "<string>",
    "follower_link": "<string>",
    "pin": "4-digit string",
    "tags": [/* list of strings */],
    "meta": "<string>",
    "start_time": "<a string representing the date and time in ISO 8601 format>"
}

session.started

Triggered when a session is created (via API call or from the Surfly website)

{
    "session_id": "<string>",
    "leader_link": "<string>",
    "follower_link": "<string>",
    "tags": [/* list of strings */],
    "meta": "<string>",
    "start_time": "<a string representing the date and time in ISO 8601 format"
}

session.ended

Triggered when a session is ended

{
    "session_id": "<string>",
    "pin": "4-digit string",
    "tags": [/* list of strings */],
    "meta": "<string>",
    "start_time": "<a string representing the date and time in ISO 8601 format>",
    "end_time": "<a string representing the date and time in ISO 8601 format>",
    "duration": "<number of seconds>",
    "videochat_minutes": "<int>",
    "max_participants": "<int>"
}

session.screenshot

Triggered when a screenshot was created

{
    "session_id": "<string>",
    "tags": [/* list of strings */],
    "meta": "<string>",
    "status": "<string>",
    "url": "<string>"
}

session.invitation

Triggered when a follower was invited to the session, there are two formats for this:

• when the session invitation is set to "email"

{
    "session_id": "<string>",
    "follower_link": "<string>",
    "to": "<string>",
    "from": "<string>",
    "invite_by": "<string with value 'email'>",
    "password": "<string, null>",
    "company_id": "<integer>",
    "start_time": "<a string representing the date and time in ISO 8601 format>"
}

• when session invitation is set to "phone"

{
    "session_id": "<string>",
    "follower_link": "<string>",
    "to": "<string with the country dial code and the phone number>",
    "invite_by": "<string with value 'sms'>",
    "password": "<string, null>",
    "company_id": "<integer>",
    "start_time": "<a string representing the date and time in ISO 8601 format>"
}

company.new_agent

Triggered when new agent was invited to the company

{
    "company_id": "<integer>",
    "agent_id": "<integer>",
    "reseller_id": "<integer>",
    "email": "<string>",
    "created": "<a string representing the date and time in ISO 8601 format>",
    "roles": [/* list of strings */],
    "activation_url": "<string>",
    "password_reset_url": "<string>"
}

company.deactivated_agents

Triggered when agents are deactivated after agents count decrease in AWS interface

{
    "company_id": "<integer>",
    "active_admin_id": "<integer>",
    "available_seats": "<integer>",
    "current_agents": "<integer>"
}

agent.password_reset

Triggered when password reset link is sent to agent, there are two cases for this:

• when the agent requests the link themselves

{
    "company_id": "<integer>",
    "agent_id": "<integer>",
    "name": "<string>",
    "email": "<string>",
    "password_reset_url": "<string>"
    "initiated_by": "<string with value 'self'>"
}

• when a reseller creates account for an agent

{
    "company_id": "<integer>",
    "agent_id": "<integer>",
    "name": "<string>",
    "email": "<string>",
    "password_reset_url": "<string>"
    "initiated_by": "<string with value 'reseller'>"
}

agent.account_activation

Triggered when an activation e-mail is sent to an agent.

{
    "company_id": "<integer>",
    "agent_id": "<integer>",
    "name": "<string>",
    "email": "<string>",
    "activation_url": "<string>"
}

session.viewer_joined

Triggered when a follower joins the session

{
    "session_id": "<string>",
    "follower_link": "<string>",
    "start_time": "<a string representing the date and time in ISO 8601 format>",
    "agent_id": "<int>",
    "user_data": {
        "name": "<string>",
        "username": "<string>",  /* same as name */
        "email": "<string>",
        "avatar": "<string>",
        "participant_prefix": "<string>",
        "queue_index": "<string>",
        "ip": "<string>",
        "user_agent": "<string>",
        /* plus the items in the query parameters that passed to the follower_link */
    }
}

session.participant_joined

Triggered when a participant joins the session

{
    "session_id": "<string>",
    "user_data": {
        "name": "<string>",
        "username": "<string>",  /* same as name */
        "email": "<string>",
        "avatar": "<string>",
        "participant_prefix": "<string>",
        "queue_index": "<string>",
        "ip": "<string>",
        "user_agent": "<string>",
        /* plus the items in the query parameters that passed to the follower_link */
    }
}

session.log

Triggered at end of the session with session logs

{
    "session_id": "<string>",
    "session_logs": "<a list of objects representing session logs>"
}

document.shared

Triggered when a document is shared

{
    "session_id": "<string>",
    "document_url": "<string>"
}

recording.started

Triggered when session recording started

{
    "session_id": "<string>"
}

recording.ended

Triggered when session recording is ended

{
    "session_id": "<string>"
}

history.extracted_as_url

Triggered when session history request has been processed and uploaded

{
    "company_id": "<integer>",
    "agent_id": "<integer>",
    "name": "<string>",
    "email": "<string>",
    "filter_params": {/* json with all the filters applied to session history request */},
    "history_url": "<string>",
}

history.extracted_as_csv

Triggered when session history request has been processed without upload

{
    "company_id": "<integer>",
    "agent_id": "<integer>",
    "name": "<string>",
    "email": "<string>",
    "filter_params": {/* json with all the filters applied to session history request */},
    "history_csv": "<text/csv string>",
}

history.extraction_failed

Triggered when session history request failed

{
    "company_id": "<integer>",
    "agent_id": "<integer>",
    "name": "<string>",
    "email": "<string>",
    "filter_params": {/* json with all the filters applied to session history request */},
}