Netzo Examples: Webhook Handling

Wed Nov 02 2022

Arturo Romero Karam

Netzo is a code-first integration platform that empowers developers to integrate APIs, code automations and build internal tools faster.

This article is part of the Netzo Examples series. The objective of this series is to offer a practical solution to a specific problem. Some of these solutions are published to the open source Netzo Marketplace as starter templates for anyone to fork.

Introduction #

What are webhooks? #

A webhook is a way for an application to provide information to other applications as this happens. Unlike typical APIs, which require the user or application no poll data in any given time interval and process changes, webhooks enhance applications with EVENT driven transactions.

In other words, you can understand a webhookas an API that is driven by events rather than through requests. This makes webhooks efficient for processing changes both for the webhookprovider and its consumer.

Handling webhooks #

As webhooks are typically sent on resource changes, they will typically execute a POST request to the consumers URL, however this does not limit a webhookto be used in other scenarios or to invoke other HTTP methods like GET, PUT, PATCH, DELETE.

Handling webhooks is typically a 2 step process, the webhookinvocation itself and the data processing afterwards.

What can I use webhooks for? #

Webhooks come in handy and are essential for many tasks. Some relevant use cases include:

• 🔄 Syncing email list subscriptions and unsubscriptions across systems
• 📰 Updating invoice status when paid
• 🔔 Setting up notifications to any interested party
• #️⃣ Automatically posting to social media on new CMS entries
• 📦 Integrating with shipping platforms

and many more.

Problem #

Webhook events can be setup in most enterprise tools like CRMs, ERPs and marketing platforms, however, webhookprocessing requires a middleman to read, map and transmit webhookdata to other systems. This can be achieved by hiring middleman services or automation platforms like Zapier and Pipedream or spinning up your own internal servers to process this requests. In any case, either your data is posted to your providers infrastructure or you will have to do the necessary investment in time and effort to setup and maintain your own infrastructure.

Solution #

The solution to handle webhookdata in a single place is to create a custom endpoint that handles webhookevents and acts as your own contained "microserver", reducing data transmission outside your organization, for example:

• 📝 Read and map webhookdata to different formats
• ✨ Consecutively GET, POST, PUT,PATCH, DELETE resources to and from any API endpoint (CRM, ERP, Billing, Marketing, Shipping, etc.)
• 🔔 Send notifications (Email, Slack, Discord, Telegram, etc.)
• 🗊 Log consent changes and collected data
• 🪝 Trigger another workflow

and more.

Why is this beneficial? #

• Eliminate niche tools that solely process webhooks
• Full data processing flexibility
• Multi system integration in a single endpoint
• Reduce data transfers outside the organization with your own lightweight microservers
• Update and deploy on a single clic
• Add or update services and APIs as required in an instant

Example #

The following example provides a custom webhook endpoint that maps the post body necessary to create and update resources across systems.

For this example, we will be handling the following webhookpayload:

{
  "event": "contact_update",
  "crm_id": "6343f4291374ea422e62576e",
  "firstName": "Juan",
  "lastName": "Perez",
  "occupation": "Sales manager",
  "email": "[email protected]",
  "phoneNumbers": "+34123456789",
  "linkedinUrl": "https://linkedin.com/in/genericName",
  "companyName": "Acme",
  "companyLinkedinUrl": "https://www.linkedin.com/company/genericName/",
  "companyWebsite": "https://acme.inc",
  "acceptedTerms": true,
  "acceptedTermsTimestamp": "2020-05-12T23:50:21.817Z",
  "acknowledgedPrivacyPolicy": true,
  "acknowledgedPrivacyPolicyTimestamp": "2020-05-12T23:50:21.817Z",
  "emailMarketing": true,
  "emailMarketingDoubleOptIn": true,
  "marketingPreferences": {
    "newsletter": true,
    "productUpdates": false,
    "promotions": false
  }
}

For each of the following handlers:

• Send notification
• Marketing platform
• Log consent
• Trigger another workflow

we will build their respective required post body accordingly. We used the following functions to handle each use case.

export function notificationHandler(data: any) {
  const body = {
    'message:': `${data.firstName} ${data.lastName} with email ${data.email}
    from ${data.companyName} updated his marketing preferences`,
  }
  return body
}

export function marketingHandler(data: any) {
  const body = {
    firstName: data.firstName,
    lastName: data.lastName,
    email: data.email,
    linkedinUrl: data.linkedinUrl,
    emailMarketing: data.emailMarketing,
    emailMarketingDoubleOptIn: data.emailMarketingDoubleOptIn,
    listSubscribe: [1],
    listUnsubscribe: [5, 3]
  }
  return body
}

export function consentHandler(data: any) {
  const body = {
    personalData: {
      firstName: data.firstName,
      lastName: data.lastName,
      position: data.occupation,
      email: data.email,
      phone: data.phoneNumbers,
      linkedinUrl: data.linkedinUrl,
    },
    legal: {
      acknowledgedPrivacyPolicy: data.acknowledgedPrivacyPolicy,
      acknowledgedPrivacyPolicyTimestamp: data.acknowledgedPrivacyPolicyTimestamp
    },
    marketingPreferences: {
      emailMarketing: data.emailMarketing,
      emailMarketingDoubleOptIn: data.emailMarketingDoubleOptIn,
      marketingPreferences: {
        newsletter: true,
        productUpdates: false,
        promotions: false,
      }
    }
  }
  return body
}

export function workflowTriggerHandler() {
  const body = {
    workflow: 'send-contract-for-electronic-signature',
    invocationTimestamp: '2020-05-12T23:50:21.817Z',
    status: 'completed'
  }
  return body
}

Demo #

Test the live demo.