QUBE Sync

Using webhooks to handle QuickBooks responses

Now that you know how to make requests to QuickBooks, you can start handling those responses in your application via Webhooks.

Setting up your endpoints

For your application to receive responses from QuickBooks, you'll need to include the webhook_url parameter when queueing a request to QuickBooks.

webhook_url = "https://your-application.com/webhooks/qube"
QubeSync.queue_request(connection_id, {
  request_json: json, 
  webhook_url: webhook_url
})

Handling Webhooks

When QuickBooks sends a response to your application, it will include the requestID you set in the request xml. You can use this requestID to match the response to the original request. QUBE will also include its own request id in response to queueing the QB request, which will also be included in the webhook payload.

Here's an example of a webhook payload:

{
    "id": "aae4b1b0-0b3b-4b3b-8b3b-0b3b4b3b4b3b",
    "connection_id": "a1b2c3d4-e5f6-4g3h-8i7j-9k0l1m2n3o4p",
    "response_json": [
      {
        "type": "CustomerQueryRs",
        "data": [
            {
              "FullName": "Babcock's Music Shop",
              "IsActive": "true",
              "ListID": "80000003-1665678791",
              "Name": "Babcock's Music Shop"
            }
          ],
          "requestID": "1",
          "statusCode": "0",
          "statusMessage": "Status OK",
          "statusSeverity": "Info"
        }
      }
    ],
    "response_xml": "<?xml version=\"1.0\"?>
      <QBXML>
        <QBXMLMsgsRs>
          <CustomerQueryRs requestID=\"1\" statusCode=\"0\" statusSeverity=\"Info\" statusMessage=\"Status OK\">
            <CustomerRet>
              <ListID>80000003-1665678791</ListID>
              <FullName>Babcock's Music Shop</FullName>
              <Name>Babcock's Music Shop</Name>
              <IsActive>true</IsActive>
            </CustomerRet>
          </CustomerQueryRs>
        </QBXMLMsgsRs>
      </QBXML>",
    "original_request_id": "aae4b1b0-0b3b-4b3b-8b3b-0b3b4b3b4b3b",
    "page_request_id": "aae4b1b0-0b3b-4b3b-8b3b-0b3b4b3b4b3b",
    "page": 1,
}

Testing locally

If you're testing your application locally, you can use a service like ngrok to expose your local server to the internet. This way, QUBE Sync can send responses to your local server.

ngrok http 3000

Use the ngrok URL as the base of your webhook_url when queueing a request.

Verifying the payload with the gem

The qube_sync gem provides a method to verify the payload signature. You can use this method to ensure the payload is coming from QUBE.

# your webhooks controller
def qube
  payload = request.body.read
  signature = request.headers['X-Qube-Signature']

  event = QubeSync.verify_and_build_webhook!(payload, signature)
  
  # Process the response in the background, so you can respond to the webhook quickly
  ProcessQuickbooksResponseJob.perform_later(event)

  head :ok
end

Here we're using a generic webhook endpoint, but you may want to create a separate endpoint for each type of request you send to QuickBooks (e.g. customer_import, invoice_created, etc.).

Next Steps