Using webhooks to integrate with Amazon EventBridge

What's my plan?

Quick Look: Admin Center > Apps and integrations > Actions and webhooks > Webhooks

Zendesk webhooks are a powerful tool to keep your other systems updated with changes in your Zendesk account. Using webhooks to integrate with Amazon EventBridge creates the opportunity for more sophisticated workflows with real-time data processing. This article describes how to use webhooks to send Zendesk events to Amazon EventBridge.

This article contains the following topics:

• Requirements for sending events to Amazon EventBridge with webhooks
• Creating your EventBridge event bus
• Creating a Lambda function to receive the webhook payload
• Creating a Zendesk webhook to connect to Amazon EventBridge

Requirements for sending events to Amazon EventBridge with webhooks

The following requirements must be met to use webhooks to connect with Amazon EventBridge:

• You must be an admin in your Zendesk account.
• You must have an AWS account with EventBridge set up.

  Additionally, you should have a basic understanding of AWS services, including EventBridge.

Creating your EventBridge event bus

Before creating the webhook, you must create an EventBridge event bus.

Note the ARN, which is required in a later step. The ARN should be formatted in the following way:

arn:aws:events:{REGION}:{AWS_ID}:event-bus/{EVENT_BUS_ID}

Creating a Lambda function to receive the webhook payload

A Lambda function is required to receive the webhook, confirm the webhook's signature, and pass the webhook payload on to the EventBridge event bus you created.

To create a Lambda function

1. Use the AWS Lambda console to create a new Lambda function. Complete the fields as need. Under the Advanced settings, select Enable function URL and then select NONE for the authentication method.

   Note the Function URL. This is the public URL you'll connect your webhook to.

2. Add the following code to the Code source window, then click Deploy.

   import json
   import hashlib
   import hmac
   import os
   import base64
   import logging
   
   import boto3
   
   LOGGER = logging.getLogger()
   LOGGER.setLevel('INFO')
   
   EVENTBRIDGE = boto3.client('events')
   
   # Set these values in your Lambda function environment variables.
   EVENT_BUS_ARN = os.environ['EVENT_BUS_ARN']
   WEBHOOK_SECRET = os.environ['WEBHOOK_SECRET'].encode('utf-8')
   
   
   def verify_signature(payload, signature, timestamp):
       '''Verify the provided webhook signature was created by Zendesk's Webhook feature.'''
       combined = timestamp + payload
       combined_bytes = combined.encode('utf-8')
       computed_hmac = hmac.new(WEBHOOK_SECRET, combined_bytes, hashlib.sha256)
       computed_signature = base64.b64encode(computed_hmac.digest()).decode('utf-8')
       return hmac.compare_digest(computed_signature, signature)
   
   
   def webhook_to_eventbridge(event):
       '''Forward the webhook body to AWS EventBridge.'''
       payload = event['body']
       signature = event['headers'].get('x-zendesk-webhook-signature', '')
       timestamp = event['headers'].get('x-zendesk-webhook-signature-timestamp', '')
   
       if not verify_signature(payload, signature, timestamp):
           LOGGER.warning('Received webhook with invalid signature')
           return {
               'statusCode': 403,
               'body': json.dumps({'message': 'Forbidden'}),
           }
   
       payload_dict = json.loads(payload) if isinstance(payload, str) else payload
       event_source = payload_dict.get('source', 'webhook.custom')
       detail_type = payload_dict.get('type', 'defaultDetailType')
   
       put_events_response = EVENTBRIDGE.put_events(
           Entries=[
               {
                   'Source': event_source,
                   'DetailType': detail_type,
                   'Detail': json.dumps(payload_dict),
                   'EventBusName': EVENT_BUS_ARN,
               }
           ]
       )
   
       response_entries = put_events_response.get('Entries', [])
       if len(response_entries) == 0 or 'ErrorCode' in response_entries[0]:
           LOGGER.error(f'Push to event bridge failed: {response_entries}')
           return {
               'statusCode': 500,
               'body': json.dumps(
                   {
                       'message': 'Failed to send event to EventBridge',
                       'response': put_events_response,
                   }
               ),
           }
   
       return {
           'statusCode': 200,
           'body': json.dumps(
               {
                   'message': 'Event successfully sent to EventBridge',
                   'response': put_events_response,
               }
           ),
       }
   
   
   def lambda_handler(event, context):
       try:
           return webhook_to_eventbridge(event)
       except Exception as e:
           LOGGER.exception('Error handling webhook')
           return {
               'statusCode': 500,
               'body': json.dumps({'message': 'Error handling webhook', 'error': str(e)}),
           }
   

3. Add two environmental variables to the Lambda function:
   • EVENT_BUS_ARN: Set this to the ARN value you got when creating the EventBridge event bus. This is the event bus location.
   • WEBHOOK_SECRET: After you create the webhook, you'll need to set this to the webhook secret.
4. Use the AWS IAM console to create a role for the AWS Lambda service.

   Note the role's name. You'll need this information to assign the role to your Lambda function.

5. After creating the role, edit it to add the EventBridge event bus ARN.
   1. Open the role.
   2. Under Step 2: Add permissions click Edit and select Create inline policy.
   3. Search for EventBridge services and select the PutEvents method.
   4. Under Resources, click Add ARNs.
   5. Enter the EventBridge event bus ARN and click Next.
   6. Enter a Name for your policy and click Create policy.
6. Use the AWS Lambda console to open the Lambda function you created and assign the IAM role to it. On the Configuration tab, select Permissions and click Edit. At the bottom of the page, select the role's name and click Save.

Creating a Zendesk webhook to connect to Amazon EventBridge

After creating the EventBridge event bus and configuring the Lambda function, you need to create the webhook itself.

To create a webhook to integrate with Amazon EventBright

1. In Admin Center, click Apps and integrations in the sidebar, then select Actions and webhooks > Webhooks.
2. Create the webhook, making sure to specify the following values:
   • Set the Endpoint URL to the Function URL you got when you created the Lambda function.
   • Set Authentication to None.
3. Click Create webhook.

Note: Zendesk generates a secret key during the creation process for each webhook. To successfully connect your webhook to Amazon EventBridge, you must copy and paste this secret key into your Lambda function's WEBHOOK_SECRET environmental variable. See Creating a Lambda function to receive the webhook payload.

Note: This article, including the integration code, is provided for general informational purposes only. Zendesk does not support or guarantee the code. Zendesk also can't provide support for third-party technologies, such as Amazon EventBridge. Post any issues you have in the comments section or try searching for a solution online.