# A PostgreSQL-based Stackable to Simplify Webhooks Integration

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](https://github.com/platformatic/pg-hooks) emerges as a solution to streamline this process.

## What is @platformatic/pg-hooks?

[@platformatic/pg-hooks](https://marketplace.platformatic.dev/#/detail/template/3953475a-4920-409d-853d-8435ee0ed576) is a powerful [PostgreSQL](https://www.postgresql.org/) based Stackable template offered by Platformatic’s [marketplace](https://marketplace.platformatic.dev/), 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](https://github.com/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](https://github.com/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](https://github.com/platformatic/pg-hooks), follow these simple steps:

```javascript
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](http://127.0.0.1:3042).

# API Tutorial

To ensure seamless integration and verify the functionality of [@platformatic/pg-hooks](https://github.com/platformatic/pg-hooks), let's walk through a short tutorial:

1\. Create a Target Service:

Begin by creating a [Platformatic Service](https://docs.platformatic.dev/docs/service/overview/) (a Fastify template) using the following command:

```plaintext
npx @platformatic/service create
```

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

```javascript
/// <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:

```plaintext
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

```plaintext
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.

```plaintext
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.

```plaintext
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](https://crontab.guru/).

## Authorization

[@platformatic/pg-hooks](https://github.com/platformatic/pg-hooks) integrates seamlessly with [@platformatic/db](https://docs.platformatic.dev/docs/db/overview), allowing for straightforward [authorization](https://docs.platformatic.dev/docs/reference/db/authorization/introduction/) setup. Configure authorization rules based on roles and entities to enforce access control within your application.

The following will configure [@platformatic/pg-hooks](https://github.com/platformatic/pg-hooks) only to accept schedule requests by an admin that knowns the PLT\_ADMIN\_SECRET env variable:

```javascript
{
 ...
 "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 f](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS)irst process to grab the lock is the leader.

Currently, the leader is responsible for cron scheduling and message delivery, with [all the peers responsible f](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS)or 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](https://github.com/platformatic/pg-hooks), a powerful Stackable designed to streamline webhooks integration, and learned how to install, set up, and use [@platformatic/pg-hooks](https://github.com/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](https://marketplace.platformatic.dev/) 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](https://marketplace.platformatic.dev/) to discover more Stackables like [@platformatic/pg-hooks](https://github.com/platformatic/pg-hooks) and elevate your development experience.