Official Python SDK for the GoHighLevel API. This library provides a convenient way to interact with GoHighLevel's APIs from applications written in Python.
# Install the SDK
pip install gohighlevel-api-clientfromhighlevelimportHighLevel# Initialize with OAuth credentialsclient=HighLevel(
client_id="your_client_id",
client_secret="your_client_secret"
)importasynciofromhighlevelimportHighLevelasyncdefoauth_example():
client=HighLevel(
client_id="your_client_id",
client_secret="your_client_secret"
)
# Step 1: Get authorization URLauth_url=client.oauth.get_authorization_url(
client_id="your_client_id",
redirect_uri="https://your-app.com/callback",
scope="contacts.readonly campaigns.readonly"
)
print(f"Visit: {auth_url}")
# Step 2: Exchange code for tokens (after user authorization).# The request body uses camelCase keys.token_data=awaitclient.oauth.get_access_token({
"clientId": "your_client_id",
"clientSecret": "your_client_secret",
"grantType": "authorization_code",
"code": "authorization_code_from_callback",
})
# token_data is the raw token response, with camelCase keys:# accessToken, refreshToken, expiresIn, userType, and locationId or companyId.# Persist it via your session storage to authenticate later requests.print("OAuth flow completed successfully!")
asyncio.run(oauth_example())It can be used to store the access and refresh token for your application.
fromhighlevelimportHighLevelfromhighlevel.storageimportMongoDBSessionStoragestorage=MongoDBSessionStorage(
connection_string="mongodb://localhost:27017",
database_name="ghl_sessions",
collection_name="jwt_tokens"
)
client=HighLevel(
client_id="your_client_id",
client_secret="your_client_secret",
session_storage=storage
)The SDK provides comprehensive webhook support for handling GoHighLevel webhook events, including automatic token management and session storage integration.
- Automatic Token Management: Handles
INSTALLandUNINSTALLwebhooks automatically - Token Storage: Generates and stores access tokens on
INSTALL, removes them onUNINSTALL - Session Management: Integrates with your chosen session storage (Memory/MongoDB)
- Auto Token Refresh: Automatically refreshes expired tokens during API calls if tokens are stored
fromhighlevelimportHighLevelfromhighlevel.storageimportMemorySessionStorage# Initialize the SDK client with session storageclient=HighLevel(
client_id="your_client_id",
client_secret="your_client_secret",
session_storage=MemorySessionStorage()
)
# Get the webhook middlewarewebhook_middleware=client.webhooks.subscribe()
@app.route('/api/webhooks/ghl', methods=['POST'])asyncdefhandle_ghl_webhook():
"""Handle incoming GoHighLevel webhooks"""# Process the webhook using the middlewareawaitwebhook_middleware(request)
# Add your custom webhook logic herereturnjsonify({"status": "success"}), 200Incoming webhooks are verified before they are processed. Configure the public key (available in your app settings) as an environment variable. If no supported signature header and matching key are present, the middleware logs a warning and skips the webhook without processing it — so configuring a key is required for webhooks to work.
| Scheme | Header | Environment variable | Notes |
|---|---|---|---|
| Ed25519 | x-ghl-signature | WEBHOOK_SIGNATURE_PUBLIC_KEY | Preferred. Used when present. |
| RSA-SHA256 | x-wh-signature | WEBHOOK_PUBLIC_KEY | Legacy fallback. |
# CLIENT_ID is also required — the webhook's appId is matched against it before processing.export CLIENT_ID="your_client_id"export WEBHOOK_SIGNATURE_PUBLIC_KEY="your_ed25519_public_key"# Optional legacy fallback:export WEBHOOK_PUBLIC_KEY="your_rsa_public_key"This project is licensed under the MIT License - see the LICENSE file for details.
See CHANGELOG.md for a list of changes and version history.