django-zengo is a Django app that provides conveniences for integrating with Zendesk.
It facilitates receiving webhook updates from Zendesk, detecting new tickets and changes to existing tickets.
pip install django-zengo
Zengo comes with a view that processes messages sent by Zendesk and allows you to perform actions upon various Zendesk events.
You need to configure your application to receive the webhook. To do so simply include it in your URL conf:
from django.contrib import admin
from django.urls import path
from zengo.views import WebhookView
urlpatterns = [
path('admin/', admin.site.urls),
path('zengo/webhook/', WebhookView.as_view())
]You need to tell Zengo how to authenticate with Zendesk:
ZENDESK_EMAILis the email of the Zendesk account you will use to interact with the API.ZENDESK_TOKENgenerated for the user above in the Zendesk web interface.ZENDESK_SUBDOMAINmust match the subdomain used in your Zendesk account.
As seen below, you need to specify And you need to set a shared secret so that the webhook view can trust incoming messages from Zendesk:
ZENGO_WEBHOOK_SECRETgenerated by your good self; make it long and random!
So, your settings should appear something along the lines of:
ZENDESK_EMAIL = "[email protected]"
ZENDESK_TOKEN = "<token-from-zendesk-webui>"
ZENDESK_SUBDOMAIN = "example"
ZENGO_WEBHOOK_SECRET = "<replace-me-with-a-great-password>"Zendesk allows for many integrations, but for the purposes of Zengo we just need to be told when a ticket has been changed.
Log in as an administrator in Zendesk, and visit Settings > Extensions > Targets > add target > HTTP target.
Add an HTTP target with a URL of your service, and choose the POST method. Ensure you've added a secret query parameter to the URL where your webhook is accessible, such that the webhook view can authorize Zendesk's webhook sends.
Next, you must configure a trigger to use the target. Visit Business Rules > Triggers > Add trigger. Add a condition that suits your needs, such as, Ticket is updated, or Ticket is created, and select an action of Notify target, selecting the previously configured target. For JSON body, enter the following:
{
"id": "{{ ticket.id }}"
}You're done! Now whenever a ticket is created or updated in Zendesk, you should have an event being processed in your application.
Note: for development, I recommend using the excellent ngrok to proxy requests through to your localhost.
When Zengo receives a webhook from Zendesk, it will fetch the latest state of the ticket from Zendesk's APIs, compare how this differs to the state in the local database models, and fire a signal indicating what has happened. In your application, you attach receivers to the signal that is most relevant to your need.
from django.dispatch import receiver
from zengo.signals import ticket_created
@receiver(ticket_created)
def handle_new_ticket(sender, ticket, context, **kwargs):
# perform your custom action here
passYou can connect to the following signals.
zengo.signals.ticket_created- fires when a ticket is encountered for the first time.zengo.signals.ticket_updated- fires when a ticket previously encountered is changed, or has a new comment added.
django-zengo supports a variety of Python and Django versions. It's best if you test each one of these before committing. Our Circle CI Integration will test these when you push but knowing before you commit prevents from having to do a lot of extra commits to get the build to pass.
In order to easily test on all these Pythons and run the exact same thing that CI will execute you'll want to setup pyenv and install the Python versions outlined in tox.ini.
If you are on Mac OS X, it's recommended you use brew. After installing brew run:
$ brew install pyenv pyenv-virtualenv pyenv-virtualenvwrapper
Then:
pyenv install -s 3.6.10
pyenv install -s 3.7.6
pyenv install -s 3.8.1
pyenv virtualenv zengo 3.8.1
pyenv shell zengo 3.6.10 3.7.6
pip install detox
To run the test suite:
$ detox