Get Satisfaction Education Center

Home > Reference Guide > API > Push API – Webhooks

Push API – Webhooks

Overview

The Get Satisfaction Push API is a Webhook-based notification system. Webhooks are triggers that cause Get Satisfaction to send an HTTP notification to a specified address each time a given event happens in the community. Webhooks are useful to avoid having to poll Get Satisfaction continually to find out if a new topic or reply has been created, or a topic has been updated.


Supported events

The Get Satisfaction Push API supports three event based triggers, and one manual trigger:

  • Topic Create
  • Topic Update
  • Reply Create
  • Manual Export

Activating Webhooks in Your Community

To use the Push API, you need to have Webhooks activated in your community. To activate Webhooks, do the following:

  1. Navigate to the Integrations page of the Admin section in your community
  2. Click the Webhook logo. A Webhook activation window will open

Get Satisfaction Push API - Webhooks

In the Webhook activation window, do the following:

  1. Give your Webhook a name
  2. Add the Endpoint URL
  3. Select the event or events you want to trigger the action. Manual Exports cannot be combined with other triggers
  4. Click “Activate”

Advanced Settings

You use authentication, or pass static information along with your Webhook calls. These settings are available in the “Advanced” area of the panel. To modify those settings, click “Advanced”. The panel will open to display authentication and query string settings.

Authentication settings

The Get Satisfaction Push API supports either Basic Access Authorization, or the OAuth protocol.

To use authentication, do the following:

  1. Open the “Advanced” Panel
  2. Select the Authentication method you want to use
  3. Enter the Username and Password (for Basic Authorization) or the Consumer Key and Secret (for OAuth)
    Query String settings
    You can pass an arbitrary query string to your endpoint along with the topic information. The parameter string should be comprised of name-value pairs, and must be URL-escaped.To pass in a query string, do the following:

    1. Open the “Advanced” Panel
    2. Enter your query string into the parameters field

    Events
    Topic create
    When a topic is created, a POST request is automatically made to the specified end-point with the following associated topic information:

    Field name Type Description
    author_email string email of the topic author IF shared with the community in question
    author_id integer user ID of the topic author
    author_name string name of the topic author
    author_url string URL to the topic author’s profile page on Get Satisfaction
    company_id integer Get Satisfaction community ID
    created_at string UTC timestamp in format “Wed Dec 15 01:05:40 UTC 2010″
    description string Get Satisfaction topic description
    event_type string name for the event that triggered the push (i.e. “topic_create” or “topic_update”)
    follower_count integer number of users following the topic
    me_too_count integer number of me-too votes for the topic
    products array list of products, each represented as a hash with keys product_id and product_name
    source string where the topic was created (e.g. “Website”, “API”, “Facebook”, etc.)
    status string Get Satisfaction topic status
    style string Get Satisfaction topic style (question, problem, idea, problem, update)
    subject string Get Satisfaction topic subject
    tags array list of tags, each represented as a hash with keys tag_id and tag_name
    topic_id integer Get Satisfaction topic ID
    topic_url string URL to topic on the Get Satisfaction site
    user_defined_codes array list of Private Tags, each as a hash with keys udc_id, udc_name, udc_canonical_name

    Topic update
    When a topic is updated, a PUT request is automatically made to the specified end-point. The data uploaded is based on what was updated in the community, as follows:

    The following parameters are always included:

    Field name Type Description
    topic_id integer Get Satisfaction topic ID
    updated_at string UTC timestamp in format “Wed Dec 15 01:05:40 UTC 2010″

    The following parameters are sent only if the attributes have changed. Also note that only changes to these attributes will trigger the PUT.

    Field name Type Description
    style string Get Satisfaction topic style (question, problem, idea, problem, update)
    subject string Get Satisfaction topic subject
    description string Get Satisfaction topic description
    status string Get Satisfaction topic status
    me_too_count integer number of me-too votes for the topic
    follower_count integer number of users following the topic
    products array list of products, each represented as a hash with keys product_id and product_name
    tags array list of tags, each represented as a hash with keys tag_id and tag_name
    user_defined_codes array list of Private Tags, each as a hash with keys udc_id, udc_name, udc_canonical_name

    Reply/Comment Create
    When a reply or comment is created, a POST request is automatically made to the specified end-point with the following associated information:

    Field name Type Description
    author_email string email address of the author IF it has been shared by the author
    author_id integer user ID of the reply or comment author
    author_name string name of the reply or comment author
    author_url string URL to the reply author’s profile page on Get Satisfaction
    body string Get Satisfaction topic description
    company_id integer Get Satisfaction community ID
    created_at string UTC timestamp in format “Wed Dec 15 01:05:40 UTC 2010″
    event_type string name for the event that triggered the push (i.e. “reply_create”)
    reply_id integer Get Satisfaction reply ID
    source string where the reply or comment was created (“Website”, “API”, “Facebook”, etc.)
    topic_id integer Get Satisfaction topic ID

    Manual Export
    When a moderator manually exports a topic, a PUT request is made to the specified listener end-point. The payload contains information for every reply (containing the same data as the Reply/Comment Create trigger) and information about the original topic (containing the same data as the Topic Create trigger) as described above.
    Error handling
    If a Push API end-point returns anything other than a 2xx response, the Push API will assume that there is an issue at the endpoint that potentially needs a human being to intervene to resolve. If a Push API call is made and the endpoint returns a code other than 2xx, the Push API will retry after 5 minutes. If there are three consecutive Push API retry calls that do not result in 2xx responses (for example, they all generate 503 status codes), the Push API will be suspended for that endpoint.

    When the Push API is suspended for a community, an email will be sent to all Admins for the community. To re-enable the integration, a community admin should do the following:

    1. Confirm that the endpoint is properly configured and setup
    2. Go into the Integration Administration page and click “Retry” next to the appropriate endpoint

System Status

Company Updates