neeto-webhooks-nano

The neeto-webhooks-nano manages webhooks within neeto applications. The nano exports the @bigbinary/neeto-webhooks-frontend NPM package and neeto-webhooks-engine Rails engine for development. Its webhook Playwright helpers are published independently as @bigbinary/neeto-webhooks-playwright from the playwright/ directory.

Contents

1. Development with Host Application
   • Engine
     • Installation
     • Usage
   • Frontend package
     • Installation
     • Components
2. Instructions for Publishing
3. Playwright helpers

Development with Host Application

Engine

The engine is used to manage webhooks across neeto products.

Installation

1. Add this line to your application's Gemfile:

   source "NEETO_GEM_SERVER_URL" do
      # ..existing gems
   
      gem 'neeto-webhooks-engine'
   
      # Use this for live development:
      # gem 'neeto-webhooks-engine', path: "../neeto-webhooks-nano"
   end
   

2. And then execute:

   bundle install
   

3. Add this line to your application's config/routes.rb file:

   mount NeetoWebhooksEngine::Engine, at: "/neeto_webhooks"
   

4. Run the following command to copy the migrations from the engine to the host application:

   rails g neeto_webhooks_engine:install
   

5. Add the migrations to the database:

   bundle exec rails db:migrate
   

6. Add the following line to application's config/initializer/neeto_webhooks_engine.rb file. Replace the event_identifiers with an array of unique keywords representing possible webhook events.

   NeetoWebhooksEngine.event_identifiers = ["create", "update", "cancel"]
   

7. Add translations for the webhook events using the key format webhooks.events.webhook_event, where webhook_event is the custom-defined event_identifier.

   webhooks:
     events:
       create: "Booking creation"
       update: "Booking reschedule"
       cancel: "Booking cancellation"
   

8. (Optional) Configure taxonomy identifiers to automatically inject taxonomy values into translation strings. The values can then be used in locale strings as interpolation variables.

   NeetoWebhooksEngine.taxonomy_identifiers = {
     customer: "singular",
     teamMember: "singular"
   }
   

9. Add the permission neeto_webhooks_engine.manage_webhooks to your permissions.yml file.

Usage

You can learn more about the setup and usage here:

1. Models
2. Webhook Versioning Implementation

Frontend package

Installation

1. Install the latest neeto-webhooks-nano package using the below command:

   yarn add @bigbinary/neeto-webhooks-frontend
   

Instructions for development

Check the Frontend package development guide for step-by-step instructions to develop the frontend package.

Components

NeetoWebhooks (source code)

This component is used to manage webhooks in your web application.

1. It provides a user interface for viewing, adding, and editing webhooks.
2. It also includes a user interface for listing deliveries and viewing delivery details, featuring tabs that display both request and response information.

Props

Both are required, and the component logs an error naming whichever is missing. They fail differently, which is worth knowing when one of them is wrong: without entityId the list cannot load at all, while without entityType the list still renders and only creating a webhook fails.

• entityType: The class name of the record that owns these webhooks, and one of the values in NeetoWebhooksEngine.valid_entity_types. Usually "Organization".
• entityId: The id of that record. Note that globalProps.organization does not carry an id in most neeto apps — it is serialized as name, subdomain, favicon and keys — so the host usually has to send the id through its own client props.

Optional Props

• breadcrumbs: An array of objects that specify breadcrumbs for navigation.
• helpLinkUrls: An object that specifies the URLs for the help links.
  • webhooks: The URL for the webhooks help link.
  • secrets: The URL for the secrets help link.
  • deliveries: The URL for the deliveries help link.

Usage

import React from "react";

import { NeetoWebhooks } from "@bigbinary/neeto-webhooks-frontend";
import { routes } from "common/routes";
import { BrowserRouter, Route, Switch } from "react-router-dom";
import { ToastContainer } from "react-toastify";

const Main = () => (
  <BrowserRouter>
    <div className="flex">
      <Switch>
        <Route
          path={routes.webhooks}
          component={() => (
            <NeetoWebhooks
              entityId={entityId}
              entityType={entityType}
              breadcrumbs={[
                {
                  text: "Settings",
                  link: routes.settings,
                },
                { text: "Webhook" },
              ]}
              helpLinkUrls={{
                webhooks:
                  "https://help.neetokb.com/articles/creating-a-webhook",
                secrets:
                  "https://help.neetokb.com/articles/securing-webhook-requests",
                deliveries:
                  "https://help.neetokb.com/articles/managing-webhook-deliveries",
              }}
            />
          )}
        />
      </Switch>
    </div>
    <ToastContainer />
  </BrowserRouter>
);

export default Main;

Instructions for Publishing

Consult the building and releasing packages guide for details on how to publish.

@bigbinary/neeto-webhooks-playwright is published separately from playwright/ when a merged PR has the playwright label and a patch, minor, or major label.