Zendesk Licensing Integration
In short: support agents see a customer’s license status without leaving Zendesk. A trigger sends a webhook when a ticket is created, your receiver validates the customer in NetLicensing and adds the result to the ticket as an internal note. In the other direction, NetLicensing notifications can update custom organization fields, so the status sits on the organization record.
Zendesk has no NetLicensing app. For the sales side, see HubSpot, Pipedrive and Zoho CRM.
What Zendesk sends
A Zendesk webhook sends an HTTP request to your URL. There are two ways to connect it: subscribe it to Zendesk events (organization, user, help center and community activity), or connect it to a trigger or automation (ticket activity). A webhook cannot do both, and you cannot change the connection method afterwards. This guide uses a trigger.
Create the webhook in Admin Center > Apps and integrations > Webhooks > Webhooks > Create webhook, choose Trigger or automation, then give it a name, the endpoint URL, the request method (POST) and the format (JSON). You must be an admin or an agent in a custom role with permission to create webhooks. Trial accounts are limited to 10 webhooks and 60 invocations per minute.
Connect it to a trigger in Admin Center > Objects and rules > Business rules > Triggers: create or edit a trigger, choose the condition for “ticket created”, and add the action Notify webhook with your webhook and a JSON payload. The payload (up to 16,000 characters) can contain placeholders, which Zendesk replaces with ticket data. Three placeholders are enough here:
| Placeholder | Value |
|---|---|
{{ticket.id}} | The ticket id |
{{ticket.requester.email}} | The requester’s email address |
{{ticket.organization.external_id}} | The external id of the requester’s organization |
Zendesk’s own documentation shows the payload as a JSON string, so a payload of {"ticketId": "{{ticket.id}}", "email": "{{ticket.requester.email}}", "orgExternalId": "{{ticket.organization.external_id}}"} is what your receiver gets.
Match Zendesk and NetLicensing
An organization in Zendesk has an optional external_id: “a unique external id to associate organizations to an external record” (case-insensitive). Set it to the NetLicensing licensee number. The trigger payload then carries the licensee number, and a customer without an organization can fall back to the requester’s email, which you can use as a licensee number or an alias. Use the platform’s ids as numbers where you can (IDs as numbers).
Secure the call
- Authentication. The webhook can add API key, basic or bearer authentication to its requests. You can also add up to five custom headers on an HTTPS endpoint; do not put credentials in them.
- Signature. You can sign requests: create a signing secret for the webhook (the webhook’s page in Admin Center shows it under Reveal secret). Zendesk then sends two headers,
X-Zendesk-Webhook-SignatureandX-Zendesk-Webhook-Signature-Timestamp. The signature isbase64(HMACSHA256(TIMESTAMP + BODY)), computed with the secret over the timestamp followed by the raw request body. Compare it in constant time. - NetLicensing side. Use an API key with the role
ROLE_APIKEY_LICENSEE, the lowest role that may validate, and senddryRun=trueso the lookup changes nothing.
Time, retries and failures
- 12 seconds. Zendesk gives a webhook request 12 seconds. A request that times out is retried up to five times, so a slow receiver can add the same note several times. Keep the work short (the example allows 4 seconds per call), or answer at once and work in the background.
- Retries on errors. After a failed first attempt Zendesk retries up to three times when your server answers
409. It also retries429and503when the answer carries aretry-afterheader of less than 60 seconds. Zendesk’s documentation lists no retries for other error codes. Answer2xxwhen the work is done, and do not return409for a permanent problem. - Circuit breaker. If 70% of a webhook’s requests fail within five minutes, or it gets more than 1,000 error responses in five minutes, Zendesk pauses it for five seconds at a time (the breaker does not trigger below 100 requests in five minutes). Failed requests never deactivate the webhook.
- No order. Webhook jobs run independently, so Zendesk does not guarantee their order.
Add the result to the ticket
Your receiver writes to Zendesk with the REST API. Comments are created by including a comment object when you update the ticket: PUT /api/v2/tickets/{ticket_id} with {"ticket": {"comment": {"body": "...", "public": false}}}. In the comment object, public is true for a public comment and false for an internal note, so agents see the result and customers do not.
Authenticate with an OAuth access token (Authorization: Bearer ...). Zendesk marks API tokens as deprecated and asks existing customers to migrate to OAuth access tokens.
Show the status on the organization
You can also keep the status on the organization, so it appears for every ticket of that customer:
- In Zendesk, an admin adds custom organization fields (for example a checkbox
netlicensing_validand a datenetlicensing_expires) in Admin Center. Custom organization fields are visible to agents and admins only. - Create a notification in NetLicensing for
LICENSE_CREATEDandWARNING_LEVEL_CHANGED. The payload names the customer:entities.License[0].licenseefor a license event andentities.Licensee[0].numberfor a warning-level event. - Your receiver validates the customer, finds the organization with
GET /api/v2/organizations/search?external_id=<licensee number>, and updates it withPUT /api/v2/organizations/{organization_id}, putting the values intoorganization_fields.
Example: the calls
Text version of this diagram (click to expand)
- Zendesk → Your receiver: webhook (JSON, signed) (12 second timeout)
- Your receiver: verify signature
- Your receiver → NetLicensing: POST .../validate (dryRun=true)
- NetLicensing → Your receiver: valid, expires
- Your receiver → Zendesk: PUT /tickets/{id} (internal note: public false)
The values below are illustrative. Code samples are Python, using only the standard library.
1. Zendesk calls your receiver
POST /hooks/zendesk HTTP/1.1
Content-Type: application/json
X-Zendesk-Webhook-Signature: <base64 signature>
X-Zendesk-Webhook-Signature-Timestamp: 2026-11-20T10:00:00Z
{"ticketId": "42", "email": "jane@example.com", "orgExternalId": "acme"}
2. Your receiver checks the signature, validates and writes the note
import base64, hashlib, hmac, json, os, urllib.error, urllib.parse, urllib.request
NLIC = "https://go.netlicensing.io/core/v2/rest"
ZENDESK = "https://example.zendesk.com"
MODULE = "MGZRTP4UR" # the product module you sell
def request(method, url, headers, body=None):
req = urllib.request.Request(url, data=body, headers=headers, method=method)
try:
with urllib.request.urlopen(req, timeout=4) as resp: # Zendesk gives the webhook 12 seconds
raw = resp.read()
return resp.status, json.loads(raw) if raw else None
except urllib.error.HTTPError as err:
return err.code, None
def signature_ok(headers, raw_body):
"""base64(HMAC-SHA256(timestamp + body)), as described in Zendesk's webhook guide."""
secret = os.environ["ZENDESK_SIGNING_SECRET"].encode()
timestamp = headers.get("X-Zendesk-Webhook-Signature-Timestamp", "").encode()
expected = base64.b64encode(hmac.new(secret, timestamp + raw_body, hashlib.sha256).digest())
return hmac.compare_digest(expected, headers.get("X-Zendesk-Webhook-Signature", "").encode())
def prop(node, name):
return next((p["value"] for p in node.get("property", []) if p["name"] == name), None)
def validate(licensee_number):
"""Returns (valid, expires), or None if NetLicensing does not know the customer."""
auth = base64.b64encode(f"apiKey:{os.environ['NETLICENSING_API_KEY']}".encode()).decode()
status, data = request(
"POST",
f"{NLIC}/licensee/{urllib.parse.quote(licensee_number, safe='')}/validate",
{"Authorization": f"Basic {auth}", "Accept": "application/json",
"Content-Type": "application/x-www-form-urlencoded"},
b"dryRun=true",
)
if status != 200: # an unknown licensee is HTTP 400 (NotFoundException)
return None
for item in (data.get("items") or {}).get("item", []):
if prop(item, "productModuleNumber") == MODULE:
valid = prop(item, "valid") == "true" or any(
prop(l, "valid") == "true" for l in item.get("list", []))
return valid, prop(item, "expires")
return False, None
def add_internal_note(ticket_id, text):
body = json.dumps({"ticket": {"comment": {"body": text, "public": False}}}).encode()
return request(
"PUT", f"{ZENDESK}/api/v2/tickets/{ticket_id}",
{"Authorization": f"Bearer {os.environ['ZENDESK_OAUTH_TOKEN']}",
"Content-Type": "application/json"},
body,
)[0]
def handle(headers, raw_body):
"""Returns the HTTP status to send back to Zendesk."""
if not signature_ok(headers, raw_body):
return 401
p = json.loads(raw_body)
number = p.get("orgExternalId") or p["email"] # the organization's external id, else the email
result = validate(number)
if result is None:
note = f"NetLicensing: no customer found for {number}."
else:
valid, expires = result
note = f"NetLicensing: license {'valid' if valid else 'NOT valid'} for {number}"
note += f", expires {expires}." if expires else "."
return 200 if add_internal_note(p["ticketId"], note) == 200 else 502
We ran this code with stand-ins for the two HTTP services, using a real NetLicensing validation response. The signature code returns the same value as the Node.js example in Zendesk’s guide. A request with a wrong signature gets 401, a known customer produces the note “license valid”, and an unknown customer produces “no customer found”.
3. The NetLicensing call
curl --user "apiKey:$NETLICENSING_LICENSEE_KEY" --header "Accept: application/json" \
--data "dryRun=true" \
https://go.netlicensing.io/core/v2/rest/licensee/acme/validate
The response has one ProductModuleValidation item per product module with a valid property (models such as Rental and Multi-feature also return valid per license or feature inside the item’s list); time-based models add expires. A licensee that does not exist is answered with HTTP 400 and the message NotFoundException.
4. The Zendesk call
curl --request PUT "https://example.zendesk.com/api/v2/tickets/42" \
--header "Authorization: Bearer $ZENDESK_OAUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{ "ticket": { "comment": { "body": "NetLicensing: license valid for acme, expires 2027-11-20.", "public": false } } }'
5. Update the organization
# Find the organization by the external id you set to the licensee number
curl "https://example.zendesk.com/api/v2/organizations/search?external_id=acme" \
--header "Authorization: Bearer $ZENDESK_OAUTH_TOKEN"
# Write the status to the custom organization fields
curl --request PUT "https://example.zendesk.com/api/v2/organizations/35436" \
--header "Authorization: Bearer $ZENDESK_OAUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{ "organization": { "organization_fields": { "netlicensing_valid": true, "netlicensing_expires": "2027-11-20" } } }'
Sources
- Zendesk: Creating and monitoring webhooks (connection methods, retries, circuit breaker)
- Zendesk: Webhook security and authentication
- Zendesk: Verifying webhook authenticity
- Zendesk help: Creating webhooks to interact with third-party systems
- Zendesk help: Placeholder reference for business rules
- Zendesk API: Tickets, Ticket comments, Organizations and Organization fields
- Zendesk API: Security and authentication
You run this integration yourself; NetLicensing does not host a Zendesk connector. The Zendesk details on this page are based on the sources above, and the NetLicensing calls it relies on were tested against the live API. Zendesk changes its platform, so verify the details against the linked pages before you go live. Back to CRM and Sales.