Back to top

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


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

session.started


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


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

session.ended


triggered when a session is ended


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

session.screenshot


triggered when a screenshot was created


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

session.invitation


triggered when a follower was invited to the session


{
    'from': "<string>",
    'session_id': "<string>",
    'start_time': "<a string representing the date and time in ISO 8601 format>",
    'to': "<string>",
    'follower_link': "<string>",
}

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>",
}

agent.password_reset


triggered when an agent requested to reset the password


{
    "company_id": "<integer>",
    "agent_id": "<integer>",
    "email": "<string>",
    "password_reset_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": "an object that contains query parameters passed to the follower_link"
}

session.session_log


triggered at end of the session with session logs


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

Generated by aglio on 16 Jul 2019