QuickBooks CloudEvents Webhooks – PHP

PHP port of the QuickBooks CloudEvents webhook sample. Implements OAuth 2.0, signature-validated webhooks, CloudEvents parsing, in-memory storage, dashboard UI, and helper endpoints.

Prerequisites

• PHP 8.2+
• Composer
• Ngrok (or similar) for webhook tunneling

Setup

composer install
cp .env.example .env
# fill QB_CLIENT_ID, QB_CLIENT_SECRET, QB_REDIRECT_URI, QB_ENVIRONMENT, WEBHOOKS_VERIFIER_TOKEN, BASE_URL

Run

composer start
ngrok http 5001

Use the ngrok URL (e.g., https://your-ngrok-id.ngrok-free.app) as BASE_URL/QB_REDIRECT_URI and when visiting the app. Configure QuickBooks webhooks to https://<ngrok>/webhooks and redirect URI to https://<ngrok>/callback (avoid mixing localhost with ngrok in one flow). The dashboard and /events.json default to showing the last 24 hours; adjust via the hours filter or ?hours= query.

Routes

• GET / home (connect/disconnect)
• GET /dashboard dashboard with stats and events (auto-refresh)
• GET /oauth/connect start OAuth
• GET /callback handle OAuth redirect
• GET /oauth/disconnect revoke & clear session
• POST /webhooks validated webhook endpoint (intuit-signature required)
• POST /webhooks/test test endpoint without signature
• GET /webhooks/details/{index} view stored event
• GET /events.json JSON feed of events + stats
• POST /api/quickbooks/{entity} fetch entity by id (requires auth, body { \"id\": \"123\" })
• GET /health health check

Notes

• Webhook signatures use HMAC-SHA256 with WEBHOOKS_VERIFIER_TOKEN over the raw payload and compared to the intuit-signature header.
• Webhooks are kept in memory (FIFO, max 100). Restarting the app clears them.
• OAuth tokens/realm are stored in session.
• For local debugging, DISABLE_STATE_CHECK defaults to true (state check disabled). This is only for development. For production, set it to false and follow QBO OAuth2 CSRF guidelines (state validation on, consistent host/port for connect/callback).

Tests

composer test

Troubleshooting

• If OAuth fails, confirm redirect URI matches the QuickBooks app configuration.
• For signature errors, ensure the verifier token matches the webhook configuration and that you forward the raw body unmodified.