Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Webhook Documentation Improvement: Fixed Grammar, Added Security Practices, Webhook Testing Tools etc. #5388

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Webhook Documentation Improvement: Fixed Grammar, Added Security Practices, Webhook Testing Tools etc. #5388

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 41 additions & 12 deletions src/docs/spot-connect/integrations/webhook.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,12 @@
# Generic Webhook
# Webhooks

Webhooks are automated messages sent from applications when an issue occurs. They have a message, or payload, and are sent to a unique URL. They are a simple mechanism and nearly every service can integrate with Spot Connect by using webhooks.
Webhooks are automated messages sent from applications when specific events occurs. They contain a payload and are sent to a unique URL. This simple mechanism allows nearly every service to integrate with Spot Connect using webhooks.

Webhook integration in a Spot Connect workflow lets you trigger an execution of a workflow after validating the webhook input. When creating a workflow, Spot Connect provides a generic webhook trigger node that can be invoked by any external application to automatically execute the workflow.

## Integration Actions

You can use this action in the Spot Connect workflow builder as part of your workflow.

* [Generic Webhook Trigger](spot-connect/integrations/webhook?id=generic-webhook-trigger)
Within the Spot Connect workflow builder, you can utilize the following action as part of your workflow:

## Generic Webhook Trigger

Expand All @@ -18,13 +16,13 @@ To automatically execute a Spot Connect workflow with a Generic Webhook event, c

If you do not already have a Spot Connect API Key, create one by completing the following steps:

1. In the left main menu, click **Connect** and click **Settings**.
2. Scroll down and under Resources, click **API Keys**.
1. In the main menu on the left, click **Connect**, then select **Settings**.
2. Scroll down to the Resources section and click **API Keys**.
3. Create an API Key and click **Save**.

#### Create a New Workflow

1. In the left main menu, click **Connect** and click **Workflows**.
1. In the main menu on the left, click **Connect** and click **Workflows**.
2. Click **New Workflow** and enter a name for the workflow.
3. Scroll down and select **Generic Webhook**.
4. Click **Create Workflow**.
Expand All @@ -34,13 +32,13 @@ If you do not already have a Spot Connect API Key, create one by completing the
5. In the center panel of the workflow builder, click the Generic Webhook trigger node to open the right panel. Under Webhook API Key Name, select the API Key you created earlier.
6. Compose your workflow and save it.

In the workflow builder, click the copy icon in each of the fields Webhook API Key Value and the Workflow Webhook URL to save the values. You can paste and save them into your text editor. When you configure the third-party application, use those saved values.
In the workflow builder, click the copy icon in each of the Webhook API Key Value and the Workflow Webhook URL fields to save the values. You can paste and save them into your text editor for later use when configuring the third-party application.

<img src="/spot-connect/_media/general-webhook-integration-2.png" />

### Connect to a Third-party Application

To trigger the execution of the Spot Connect workflow you created, a third-party system needs to send a POST request to a specific webhook URL, with an authorized API key included in the request header x-api-key. You can use Postman to test this.
To trigger the execution of the Spot Connect workflow you created, a third-party system needs to send a POST request to a specific webhook URL, with an authorized API key included in the request header x-api-key. You can use Postman to test this setup.

1. Log in to Postman.
2. Create a new POST request using Workflow Webhook URL value saved from Spot Connect.
Expand All @@ -58,6 +56,37 @@ Create a webhook request from Postman to trigger a workflow execution in Spot Co

<img src="/spot-connect/_media/general-webhook-integration-3.png" />

The workflow execution from the webhook request.
The workflow execution resulting from the webhook request will be displayed accordingly.

<img src="/spot-connect/_media/general-webhook-integration-4.png" />

## Testing Webhooks

### Beeceptor

[Beeceptor](https://beeceptor.tech/webhook-integration/) allows developers to create mock API endpoints effortlessly, enabling the capture and inspection of HTTP traffic in real-time. This is particularly useful for testing webhooks during development.

It’s local tunneling feature enables developers to route external event payloads directly to their local development environment. This capability facilitates immediate testing and debugging without necessitating repeated deployments, thereby expediting the development process.

**Key Benefits**:
- **Immediate Testing and Debugging**: Developers can test and debug in real-time within their local setup.
- **Faster Integration**: By eliminating the need for frequent deployments, the integration process is significantly accelerated.

### ngrok

[ngrok](https://ngrok.com/) provides a public URL that forwards requests to your local server, enabling you to test webhooks without deploying your application to a public environment. This setup is particularly useful for debugging and validating webhook integrations in real-time.

> **Note:** Exercise caution when using external tools to avoid exposing sensitive information or compromising system security.

## Security Best Practices for Webhooks
Implementing robust security measures is crucial when handling webhooks to protect your system from unauthorized access and data breaches. Key practices include:

- **Use HTTPS and SSL Verification**: Ensure that your webhook endpoints are accessible over HTTPS to encrypt data in transit, preventing interception and tampering.
- **Verify Payloads with Secrets**: Utilize a shared secret between Spot Connect and your application to validate incoming webhook requests, confirming their authenticity.
- **Validate Incoming Data**: Implement rigorous validation and sanitization procedures for any data received through webhooks, and always treat incoming data as untrusted.

## Logging and Monitoring Webhook Events
Maintaining comprehensive logs and monitoring systems is vital for tracking webhook events and diagnosing issues.

<img src="/spot-connect/_media/general-webhook-integration-4.png" />
- **Log Webhook Events**: Record details of incoming webhook requests, including headers, payloads, and response statuses, to facilitate debugging and auditing.
- **Monitor for Anomalies**: Set up alerts to detect unusual patterns, such as a sudden spike in webhook traffic or repeated failures, enabling prompt investigation and resolution.