Beehive AI supports secure and scalable webhook ingestion for Zendesk outbound webhooks using a robust, custom authentication scheme based on Google Cloud KMS-signed JSON Web Tokens (JWTs). This integration allows Private Key Isolation (KMS), Instant Revocation, Multi-Client Isolation, and Transport Security enforced over HTTPS with TLS 1.3+.
Getting Started
To begin automatically sending new ticket data to Beehive AI for analysis, you'll need to request credentials, configure the Zendesk webhook, and create a trigger.
1. Request Long-Lived JWT Credential
Contact Beehive AI Support to begin the onboarding process.
We will provide a dedicated Cloud KMS Asymmetric Signing Key for your Zendesk instance.
Once configured, we will securely share a long-lived JWT. This token is cryptographically signed using your dedicated KMS key.
Note: Your JWT grants access to the Zendesk Webhook API and includes an Issuer (iss) and Subject (sub) claim unique to your organization.
2. Configure the Zendesk Webhook (Step 1)
In your Zendesk Admin Center, create a new Webhook that points to our API and includes a custom authorization header
Path: Apps and integrations -> Webhooks -> Webhooks -> Create webhook
Configuration Field | Required Value | Notes |
Connection Method | Trigger or automation | To connect the webhook using a business rule. |
Endpoint URL | The endpoint you want to pass data to. | |
Request Method | POST |
|
Request Format | JSON |
|
Authentication | API Key |
|
Sample:
3. Add Custom Authorization Header
Store the long-lived JWT as a custom header under the Headers section.
Header Key | Header Value | Notes |
Header Name (Key) | X-Webhook-Token |
|
Value |
YOUR_LONG_LIVED_KMS_SIGNED_JWT | Replace this placeholder with the unique token provided by Beehive AI Support. This token is static and will not expire for a very long period |
Content-Type | application/json |
|
4. Create a Trigger (Step 2: Call the Webhook API)
Once the webhook is configured, create a Zendesk Trigger to execute the webhook for new tickets.
Set the trigger condition to fire when a Ticket is Created.
Verification Process
Upon receiving the request, our backend handler performs the following checks:
Extracts the JWT from the X-Webhook-Token header.
Fetches the corresponding key from Google Cloud KMS.
Verifies the cryptographic signature of the JWT using the public key.
Validates all standard claims and your custom claims (iss, sub) to ensure the token is authentic, unexpired, and belongs to your client.
If all checks pass, the webhook payload is ingested for processing.
Security Considerations
Beehive AI uses a multi-tenant security model where each client (Zendesk instance) has a dedicated asymmetric signing key managed within Google Cloud KMS.
Since Zendesk cannot refresh tokens, we use a static, long-lived JWT stored in a custom header for authentication.
Key Security Benefits
Private Key Isolation (KMS): The critical private key used to sign the JWT never leaves Google Cloud KMS. Verification requires only the publicly exposed key.
Instant Revocation: The long-lived JWT can be instantly revoked by Beehive AI by simply disabling the specific KMS Key Version that signed the token. Any subsequent webhook requests using that JWT will immediately fail signature verification.
Multi-Client Isolation: Each customer is provisioned with a dedicated KMS key, guaranteeing cryptographic isolation between clients.
Transport Security: Webhook traffic is strictly enforced over HTTPS with TLS 1.3+.