Connect external apps to Gorgias and create sidebar widgetsUpdated 5 minutes ago

In the Gorgias App Store, you can browse apps that allow you to bring third-party data into your helpdesk. If you’re looking to connect to a platform that doesn’t have an existing app in our App Store, you can build an HTTP integration using the third-party's public API. You might use an HTTP integration to automatically fetch data to display alongside tickets, or to trigger an action in an external system whenever a ticket event occurs.

Requirements

• Available on all Helpdesk plans
• Only Admins can create and manage HTTP integrations

Set up an HTTP integration

Before you start, you'll need the API endpoint URL from the third-party app you'd like to connect, the HTTP method it expects, and any authentication details; such as an API key. Refer to the app's API documentation for these details.

1. From your helpdesk, click the  Settings icon in the bottom-left corner.
2. In the menu, locate Apps, then select HTTP integration.
3. Click the Manage tab, then select Add HTTP Integration.
4. In the Integration name field, enter a descriptive name for the integration.
5. In the URL field, enter the endpoint URL.
6. Set the HTTP Method to match what the external API requires (GET, POST, PUT, or DELETE).
7. If the method is not GET, select the Request content type (application/json or application/x-www-form-urlencoded) and configure the request body.
8. If your API requires authentication, you have two options:
   • Header-based: Add the necessary key-value pairs under Header — for example, Authorization: Bearer <your-api-key>.
   • OAuth2: Toggle on Enable authentication method: OAuth2 and fill in the Token URL, Client ID, Client Secret, Token Location (Header or Query String), Token Key, and optionally Scopes.
9. Under Triggers, select the ticket events that should fire this integration. The available triggers are Ticket created, Ticket updated, Ticket self unsnoozed, Ticket message created, and Ticket message failed. Note that Ticket assignment updated and Ticket status updated are mutually exclusive with the others — selecting either one disables the rest.
10. Click Add integration.
    
    

Display fetched data in the ticket sidebar

If your integration fetches customer data from an external system, you can surface it in the ticket sidebar as a custom widget.

1. Open a ticket relevant to the data your integration is built to return.
2. Click the  gear icon in the ticket sidebar to open widget settings.
3. Click the six dots icon on the section that contains your integration's data, then drag it into the sidebar.
4. You can customize which variables the widget displays in the ticket sidebar, and how they're displayed. Hover over a variable, then click the  trash can icon to remove it from the widget, or the  pencil icon to change the name or type of variable. 
5. To change widget's border color, click  Customize Widget. To remove the widget from the ticket sidebar, click  Delete Widget. 

Once set up, the sidebar will automatically show the fetched data for every new ticket. You can also reference this data in macros using back-office variables — see the Macro variables article for details.

Reliability and event delivery

HTTP integrations rely on your endpoint being reachable when ticket events fire. Each request has a 5-second timeout. If a request fails due to a connection error or timeout, Gorgias will retry it up to 3 times with exponential backoff: starting at 10 seconds, then 20, then 40.

Review integration event logs

Gorgias disables an HTTP integration automatically if 500 consecutive requests to your endpoint fail. Common causes include downtime on the receiving service, latency issues causing requests to time out, or a misconfigured endpoint URL. If you've received a notification that your integration was disabled, fix the underlying issue first, then re-enable the integration in Gorgias.

Gorgias resets the failure count back to zero after a successful request is delivered. This means the occasional failure won't cause the integration to be disabled, only a sustained run of 500 consecutive failures will.

To troubleshoot the specific requests that failed, check the Events log for your integration:

1. From your helpdesk, click the  Settings icon in the bottom-left corner.
2. In the menu, locate Apps, then select HTTP integration.
3. Click the Manage tab, then an existing integration from the list.
4. Click the Events tab to review the latest requests sent by the integration.
5. Click any request to view more details. 
   
   

FAQ