Webhooks, a key aspect of modern web development, facilitate seamless communication between applications and services. They allow one application to send automated messages or notifications to another application when specific events occur. Instead of requiring continuous polling or manual checks for updates, webhooks enable instant notifications, triggering actions based on predefined events.

Despite their importance in building dynamic and responsive applications, integrating webhooks into applications can pose significant challenges for developers. These challenges range from managing delayed/scheduled invocations to handling automatic retries and ensuring robust error handling, and can often lead to inefficiencies and roadblocks in the development process.

This blog post examines webhooks integration and how @platformatic/pg-hooks emerges as a solution to streamline this process.

What is @platformatic/pg-hooks?

@platformatic/pg-hooks is a powerful PostgreSQL based Stackable template offered by Platformatic’s marketplace, designed to simplify the integration of webhooks into applications.

This Stackable provides a comprehensive solution for managing webhooks within applications. It addresses common challenges developers face in ensuring reliable and efficient event-driven communication between different components of their systems. Whether you are building a new application from scratch or adding webhooks functionality to an existing project, @platformatic/pg-hooks simplifies the process.

Key features include:

1. Delayed/Scheduled Invocation: Schedule web hook invocations easily, ensuring timely execution of critical tasks.

2. Automatic Retries: Seamlessly handle failures with automatic retry mechanisms, enhancing the robustness of your application.

3. Leader/Follower System: Implement a leader/follower system with election capabilities to ensure efficient task distribution.

4. Dead Letter Queue: A dead letter queue provides a mechanism for handling undeliverable messages and safeguards against message loss.

5. CRON Integration: Integrate CRON jobs effortlessly, allowing for the execution of recurring tasks according to a specified schedule.

Moreover, @platformatic/pg-hooks is a valuable tool for creating an outbox, facilitating reliable message delivery within your application architecture.

Standalone Install & Setup

To get started with @platformatic/pg-hooks, follow these simple steps:

npx --package @platformatic/pg-hooks -c create-platformatic-pg-hooks
cd pg-hooks-app
npm i
npx plt start

You can then edit your .env file and configure the DB_URL env variable to select a PostgreSQL database.

To familiarize yourself with the API endpoints, explore the OpenAPI and GraphQL definitions available at http://127.0.0.1:3042.

API Tutorial

To ensure seamless integration and verify the functionality of @platformatic/pg-hooks, let's walk through a short tutorial:

1. Create a Target Service:

Begin by creating a Platformatic Service (a Fastify template) using the following command:

npx @platformatic/service create

2. Now, create a platformatic-service/routes/hook.js file with the following content:

/// <reference path="../global.d.ts" />
'use strict'
/** @param {import('fastify').FastifyInstance} fastify */
module.exports = async function (fastify, opts) {
  fastify.post('/receive-my-hook', async (request, reply) => {
    request.log.info({ body: request.body }, 'Received hook')
    return 'ok'
  })
}

3. Then, edit platformatic-service/.env and platformatic-service/.env.sample so that PORT=3001

4. Run plt start to start your app. To verify that your application is working as expected, in another shell run:

curl -X POST -H 'Content-Type: application/json' -d '{ "hello": "world" }' http://127.0.0.1:3001/receive-my-hook

This will print ok and log the received body in the console.

5. Create a queue using either OpenAPI or GraphQL web pages or the following curl command

curl --request POST \
  --url http://127.0.0.1:3042/queues/ \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "my test",
  "callbackUrl": "http://127.0.0.1:3001/receive-my-hook",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "maxRetries": 1
}'

6. Generate a message within the created queue to observe message delivery and processing.

curl --request POST \
  --url http://0.0.0.0:3042/messages/ \
  --header 'Content-Type: application/json' \
  --data '{
  "queueId": 1,
  "body": "{ \"hello\": \"world\" }"
}'

Watch the logs in both the service and the pg-hooks app.

7. As a final and optional step, you can set up a CRON job to execute recurring tasks using the provided CURL command.

curl --request POST \
  --url http://0.0.0.0:3042/cron/ \
  --header 'Content-Type: application/json' \
  --data '{
  "queueId": 2,
  "schedule": "* * * * *",
  "body": "{ \"hello\": \"world\" }"
}'

If you need a refresher on the CRON syntax, check out crontab.guru.

Authorization

@platformatic/pg-hooks integrates seamlessly with @platformatic/db, allowing for straightforward authorization setup. Configure authorization rules based on roles and entities to enforce access control within your application.

The following will configure @platformatic/pg-hooks only to accept schedule requests by an admin that knowns the PLT_ADMIN_SECRET env variable:

{
 ...
 "authorization": {
    "adminSecret": "{PLT_ADMIN_SECRET}",
    "rules": [
      {
        "role": "anonymous",
        "entity": "queue",
        "find": false,
        "save": false,
        "delete": false
      },
      {
        "role": "anonymous",
        "entity": "cron",
        "find": false,
        "save": false,
        "delete": false
      },
      {
        "role": "anonymous",
        "entity": "message",
        "find": false,
        "save": false,
        "delete": false
      }
    ]
  },
  ...
}

For every HTTP request, an X-PLATFORMATIC-ADMIN-SECRET header must be set with the same content as PLT_ADMIN_SECRET.

Leader Election

@platformatic/pg-hooks elect a Leader using a PostgreSQL Advisory Locks, with a first-comes-win election: the first process to grab the lock is the leader.

Currently, the leader is responsible for cron scheduling and message delivery, with all the peers responsible for creating queues and storing messages in the database.

Wrapping up

In this blog post, we've discussed the significance of webhooks in modern web development and the challenges developers encounter when integrating them into applications.

We also explored @platformatic/pg-hooks, a powerful Stackable designed to streamline webhooks integration, and learned how to install, set up, and use @platformatic/pg-hooks.

Discover Stackables

With Stackables, developers can take their code and configurations, encapsulate them into augmented npm modules, and publish them on their internal npm registry. Stackables templates come fully loaded with everything your team needs, including automatic updates, and allow for the simple layering of your specific configurations.

The Stackables Marketplace is a one-stop destination for reusing, composing, and publishing microservices and templates. Through the marketplace, developers can now discover and combine new stackables effortlessly, with seamlessly integrated Fastify plugins.

Visit the Stackables Marketplace to discover more Stackables like @platformatic/pg-hooks and elevate your development experience.