Link
✎

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-Signature and X-Zendesk-Webhook-Signature-Timestamp. The signature is base64(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 send dryRun=true so 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 retries 429 and 503 when the answer carries a retry-after header of less than 60 seconds. Zendesk’s documentation lists no retries for other error codes. Answer 2xx when the work is done, and do not return 409 for 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:

  1. In Zendesk, an admin adds custom organization fields (for example a checkbox netlicensing_valid and a date netlicensing_expires) in Admin Center. Custom organization fields are visible to agents and admins only.
  2. Create a notification in NetLicensing for LICENSE_CREATED and WARNING_LEVEL_CHANGED. The payload names the customer: entities.License[0].licensee for a license event and entities.Licensee[0].number for a warning-level event.
  3. Your receiver validates the customer, finds the organization with GET /api/v2/organizations/search?external_id=<licensee number>, and updates it with PUT /api/v2/organizations/{organization_id}, putting the values into organization_fields.

Example: the calls

A Zendesk 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.

Text version of this diagram (click to expand)
  1. Zendesk → Your receiver: webhook (JSON, signed) (12 second timeout)
  2. Your receiver: verify signature
  3. Your receiver → NetLicensing: POST .../validate (dryRun=true)
  4. NetLicensing → Your receiver: valid, expires
  5. 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


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.