Publish new Articles to Slack via the new Webhooks for Zendesk Help Center

Learn how to publish Zendesk Guide articles to Slack by using the new Zendesk Events for Guide webhooks.

Publish new Articles to Slack via the new Webhooks for Zendesk Help Center

Zendesk announced webhooks for their Help Center this week. A pretty cool new expansion on the existing Zendesk Event Webhooks feature introduced last year. Building on top of the existing users, agent, groups and organisation events, you can now get notified for changes in your articles (or community).

Announcing webhooks for help center and community events
Announced onRollout on April 26, 2023April 26, 2023 After launching the ability to set up webhooks that can receive Zendesk events last year, we’re excited to release support for initiating…

You can get notified on the following Help Center events:

  • Any help center article events
  • Article published and/or unpublished
  • Article subscription created
  • Article vote created/changed/removed
  • Article comment published/unpublished/created/changed

And for each event you get a POST request to a webhook endpoint of your choice:

{
    "account_id": 10168721,
    "detail": {
        "brand_id": "224348602",
        "id": "7005414006398"
    },
    "event": {
        "author_id": "225859532",
        "category_id": "7005437869694",
        "locale": "en-us",
        "section_id": "7005437870078",
        "title": "James Bond Gadgets"
    },
    "id": "01GX4P86AC7T0AFF86QGAHTEFR",
    "subject": "zen:article:7005414006398",
    "time": "2023-04-03T23:11:49.571545199Z",
    "type": "zen:event-type:article.published",
    "zendesk_event_version": "2022-11-06"
}

What's possible now?

I used to follow all sections on my Help Centers with a dedicated end-user and then monitor that users' mailbox for changes. I wuld then use Zapier or Cloudflare Workers for Email to automate flows based on received emails to monitor and then automate based on changes in Guide.

These new webhooks allow me to tear down that Rube Goldberg Machine of an automation flow and use cleaner and more efficient code.

Examples:

  • Notify your teams via Slack about article publications
  • Post new articles to Twitter, Facebook or other socials via Zapier
  • Notify your Marketing team so they can add it to release notes
  • ...

In this article we'll build a quick example that pushes any new article to Slack to notify your internal teams.

If you like these kind of implementation demos of new Zendesk features, please consider subscribing to this newsletter. It's free. (Or optionally paid if you really like it)

Every new subscriber motivates me to keep putting in the effort.

Thanks,
Thomas

Webhook JSON Payload

The payload you receive contains a few elements:

  • "type": "zen:event-type:article.published" defines the type of event pushed.
  • "event": {...} contains the author, category, section, locale and title of the article.
  • "detail": {...} contains the brand (useful for multibrand environments) and article ID

Post new articles to Slack

Setup a new Slack app

Any integration that posts messages to Slack requires a Slack App.

An introduction to the Slack platform
Slack apps and workflows extend, expand, and automate your Slack workspace. Cultivate conversation, inspire action, and integrate services by building an app or workflow.

Start by going to https://api.slack.com/apps and create a new app.

  • You need to configure the Webhook Feature and create a new Webhook that points to a channel of your choice.
  • In the Basic Information settings you can give the app a Name, Logo and description.

Once you setup a Webhook you'll get an URL you can use in the next step:

https://hooks.slack.com/services/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

Create Message Payload

To create a nicely formatted message you can use Slack's Block Builder to build a nice message with buttons and text.

{
    "blocks": [
      {
        "type": "section",
        "text": {
          "type": "mrkdwn",
          "text": "New article published on our Help Center"
        }
      },
      {
        "type": "section",
        "text": {
          "type": "mrkdwn",
          "text": "Title"
        },
        "accessory": {
          "type": "button",
          "text": {
            "type": "plain_text",
            "text": "View Article",
            "emoji": true
          },
          "value": "article",
          "url": https://internalnote.com,
          "action_id": "button-action"
        }
      }
    ]
  }

Setup a Cloudflare Worker

You could handle the incoming webhook in a variety of platforms, but I prefer to use Cloudflare Workers since they are free, fast and easy to use (and can be run in a Carbon Neutral Green mode).

You can find the full code in the Repository below, or follow along to learn how it works.

GitHub - verschoren/helpcenter_webhooks: Capture incoming Help Center Webhooks and push them to Slakc
Capture incoming Help Center Webhooks and push them to Slakc - GitHub - verschoren/helpcenter_webhooks: Capture incoming Help Center Webhooks and push them to Slakc
⚠️
If you're not familiar with Cloudflare Workers you could setup the same flow with Zapier. The downside is that Zapier Webhooks (needed to capture the webhook from Zendesk) are a Premium feature.

The worker is pretty straight forward. We first retrieve the POST JSON payload Zendesk sends to the Worker.

Next we retrieve the article ID, title, and locale from the payload. We then build a full url for the article.

export default {
	async fetch(request, env) {
        const { url } = request;
        const article = await request.json();

		var article_id = article.detail.id;
        var article_title = article.event.title;
		var locale = article.event.locale;
		var base = 'https://support.internalnote.com/hc/';
      	
        var full_url = `${base}${locale}/articles/${article_id}`
      	var slack = await postToSlack(full_url,article_title);
      	return new Response('pushed to Slack');
	}
}

Once we have all the variables we need, we insert them into our message payload and post our message to Slack using the webhook URL we got from creating a Slack App earlier.

async function postToSlack(full_url,article_title){
    var message = JSON.stringify({
		"blocks": [
			{
				"type": "section",
                "text": {
                	"type": "mrkdwn",
                	"text": "New article published on our Help Center"
				}
			},
			{
                "type": "section",
                "text": {
					"type": "mrkdwn",
					"text": article_title
				},
                "accessory": {
					"type": "button",
					"text": {
                        "type": "plain_text",
                        "text": "View Article",
                        "emoji": true
                    },
					"value": "article",
					"url": full_url,
					"action_id": "button-action"
				}
			}
		]
	});

	const url = "https://hooks.slack.com/services/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";
	const init = {
		body: message,
		method: 'POST',
		headers: {'content-type': 'application/json',},
	};
  
	const response = await fetch(url, init);
	return response;
}

Webhook

Now we can finally link all items together and start using the new Webhook functionality in Zendesk:

  1. Go to the Admin Center and choose Apps and Integrations. Click on Webhooks
  2. Create a new webhook by clicking the button top right
  3. Choose Zendesk Events and select Article Published from the list of options
  4. Press Next
  5. Enter a Name, Description, and the URL of your Worker. Ignore all other settings.
  6. Press Test. You should get a Slack Notification.
  7. Once the test runs successful press Create Webhook to enable the flow.

Result

Every published article in Guide will now become a Message in a Slack Channel of your choice!

So, what's next?

I really like these kind of additions to the Zendesk platform. They make integrating Zendesk into a company or workflow way easier than before. You could imagine flows where a downvoted article generates an alert for a Guide Admin to take a look, or where comments ping a moderator to take a look.

Looking further I'd really love to see the Zendesk Enterprise approval flows be available as Events too. Instead of emailing an author about approving changes, you could ping them in Slack, or add a task in Asana for them to take a look at the article.

There's always a wishlist for these new features ;-)

So what are you building?

🥳
Thanks for reading this article and the blog. If you liked this content, please consider subscribing via email or share the article to your colleagues.