Connection Webhooks

You will receive notifications via a webhook whenever there are new events associated with a Connection. All webhooks related to a connection have a type of CONNECTION.

INITIAL_UPDATE

This webhook fires after an initial data download for a Connection has been completed. You can now send requests to Rutter to fetch merchant data.

{
 "type": "CONNECTION",
 "code": "INITIAL_UPDATE",
 "connection_id": "3adc1519-0d6e-4222-83de-25b457cf42be",
 "access_token": "313c3e00-2bbc-4b2e-a9dc-13abed546b65"
}

Attempting to fetch data from a Connection without receiving the INITIAL_UPDATE webhook will return a PRODUCT_NOT_READY error.

HISTORICAL_UPDATE

If your organization has data batching enabled, this webhook will fire after a batch of historical data for a Connection has been synchronized. You can continue to fetch data while this process occurs.

📘

HISTORICAL_UPDATE will only fire if you have data batching enabled.

{
 "type": "CONNECTION",
 "code": "HISTORICAL_UPDATE",
 "connection_id": "3adc1519-0d6e-4222-83de-25b457cf42be",
 "access_token": "313c3e00-2bbc-4b2e-a9dc-13abed546b65",
 "entities_included_to_time_range": [
      {
         "platformEntity":"ORDERS",
            "xMonthsAgo":1
    },
    {   
       "platformEntity":"CREDIT_MEMOS",
        "xMonthsAgo":1
    }
    ], // Array containing information about which objects have been synchronized
}

CONNECTION_UPDATED

This webhook fires after a merchant re-authenticates an existing Connection, or after completing authentication for a created connection. The access_token value stays the same even if the Connection is updated.

{
 "type": "CONNECTION",
 "code": "CONNECTION_UPDATED",
 "connection_id": "3adc1519-0d6e-4222-83de-25b457cf42be",
 "access_token": "313c3e00-2bbc-4b2e-a9dc-13abed546b65",
 "store_unique_id": "AWMFIE33LD"
}

CONNECTION_NEEDS_UPDATE

This webhook fires after a merchant unauthorizes/uninstalls an existing Connection, or if the authentication fails for any other reason. The webhook payload includes a URL that you can share directly with the merchant to re-authenticate them.

{
 "type": "CONNECTION",
 "code": "CONNECTION_NEEDS_UPDATE",
 "connection_id": "3adc1519-0d6e-4222-83de-25b457cf42be",
 "access_token": "313c3e00-2bbc-4b2e-a9dc-13abed546b65",
 "update_url": "https://link.rutterapi.com/connection/3adc1519-0d6e-4222-83de-25b457cf42be"
}

CONNECTION_DISABLED

This webhook fires after Rutter has encountered a problem with a connection and has temporarily disabled access to it. For example, the merchant's store got suspended by the platform, it would cause the connection to be disabled. Usually, there are additional steps this merchant needs to do in beyond simply reauthenticating depending on circumstances. To understand why it's disabled, you can use Fetch a Connection Status to find out and take actions accordingly with merchants.

{
 "type": "CONNECTION",
 "code": "CONNECTION_DISABLED",
 "connection_id": "3adc1519-0d6e-4222-83de-25b457cf42be",
 "access_token": "313c3e00-2bbc-4b2e-a9dc-13abed546b65",
 "disable_error": "Reached same error over 100 times",
 "disable_message": "Error: HTTP server returned 500"
}

CONNECTION_LINK_ERROR

This webhook fires after an error occurs during the authentication process. The webhook payload includes some human-readable details around the error, and a URL that you can share directly with the merchant to re-authenticate them.

{
 "type": "CONNECTION",
 "code": "CONNECTION_LINK_ERROR",
 "connection_id": "3adc1519-0d6e-4222-83de-25b457cf42be",
 "access_token": "313c3e00-2bbc-4b2e-a9dc-13abed546b65",
 "update_url": "https://link.rutterapi.com/connection/3adc1519-0d6e-4222-83de-25b457cf42be",
 "message": "The merchant denied access during OAuth",
 "platform": "SHOPIFY"
}

CONNECTION_ERROR

This webhook after an error occurs for a connection. Errors can be related to data synchronization or issues connecting to a merchant's store after authentication is complete. The error message will contain information about the connection issue.

{
 "type": "CONNECTION",
 "code": "CONNECTION_ERROR",
 "connection_id": "3adc1519-0d6e-4222-83de-25b457cf42be",
 "access_token": "313c3e00-2bbc-4b2e-a9dc-13abed546b65",
 "message": "Cloudflare is enabled on this store and Rutter requests are blocked.",
}