Webhooks

The Webhooks section of Floogos centralizes the administration of all HTTP endpoints that trigger workflows. From here you can view the status of your webhooks, assign security policies, and analyze access traffic.

Main Indicators (KPIs)

At the top of the page, 4 summary cards are displayed, calculated in real time:

Indicator	Description
Total Webhooks	Number of webhooks configured in your account
Calls 24h	Sum of all requests received in the last 24 hours
Blocked 24h	Requests rejected by security policies in the last 24 hours
With policy	Webhooks with a security policy assigned, with the percentage protected

Webhook List

The table shows a summary of each webhook with the following columns:

Column	Description
Workflow	Name of the associated workflow with direct access to the editor
Node	Identifier of the Webhook node within the workflow
Security	Active badges: Rate, IP, HMAC based on the assigned policy
24h	Calls received and blocked in the last 24 hours
⚙	Button to open the detail side panel

Side Panel (Drawer)

Clicking ⚙ on any webhook opens a side panel with three sections:

URLs

Shows the two webhook URLs ready to copy:

• LIVE (green) — Production URL: .../webhooks/<hash>
• DEV (blue) — Development URL: .../webhooks-dev/<hash>

Security Policy

Selector to assign an existing policy to the webhook. When the selection changes, the security badges in the table update immediately without reloading the page.

If the webhook has no policy assigned, a warning appears indicating that any IP can call it without restrictions.

When a policy is assigned, two additional action buttons appear next to the selector:

Button	Action
✏️ Edit	Opens the policy modal pre-filled with its current configuration for editing
🗑️ Delete	Shows a confirmation dialog before permanently deleting the policy. Webhooks using it will have their policy removed immediately

The New button opens the policy creation modal to create a new policy from scratch.

Quick Stats (30 days)

Four metrics for the period and a daily area chart:

Metric	Description
Total	Total requests in 30 days
Blocked	Sum of blocked and rate-limited
Success rate	allowed / total × 100
Avg ms	Average workflow execution time

Below the chart, the last 8 calls from the past 7 days are shown with IP, status, block reason, and duration.

The Insights button in the panel header navigates to the full insights page.

---

Orphaned webhooks

A webhook becomes orphaned when it loses its association with a valid workflow. This happens in two cases:

• Workflow deleted — the workflow the webhook pointed to was removed.
• Node removed — the workflow still exists but the Webhook/FormTrigger node that triggered it is no longer in the flow.

Orphaned webhooks do not appear in the main list (which only shows those linked to an existing workflow), so they stay hidden in the database with no way to manage them from the normal table. They no longer trigger any execution, but it’s good practice to clean them up.

Detect and clean

The Detect orphans button, in the top bar of the Webhooks section, opens a dialog listing every orphaned webhook in your account:

Column	Description
Reason	Workflow deleted, Node removed, or No workflow
Workflow ID	Identifier of the workflow it pointed to
Node	Node that triggered it (e.g. FormTrigger_2)
Hash	Unique webhook hash
Created	Creation date

From the dialog you can:

• Select webhooks individually (or all with the header switch) and click Delete selected.
• Delete all orphans at once.

Cleanup is safe: the server re-validates each webhook before deleting it and never removes one that has a valid workflow, even if its hash is included in the request. When no orphans remain, the dialog shows a green confirmation.

Prevention

Deleting a workflow does not automatically remove its webhooks, so new orphans can appear. Run Detect orphans periodically to keep them clean.

---

Security Policies

Policies are reusable configurations that can be assigned to one or more webhooks. They are managed from the New security policy button.

Automatic Name

The policy name is generated automatically based on the active configuration:

• 100 req/60s — rate limiting active
• IP whitelist or IP blacklist — IP filtering active
• HMAC — signature enabled
• Schedule 08:00–20:00 — time restriction active

If the user edits the name manually, it stops auto-updating. The ↺ button restores the automatic name.

Rate Limiting

Limits the number of requests the webhook can receive in a time window.

Field	Description
Max requests	Maximum number of allowed requests in the window
Window (sec)	Duration of the window in seconds
Scope	Per IP (independent counter per IP) or Global (shared counter)

When the limit is exceeded, the webhook returns 429 Too Many Requests with a retry_after field indicating how many seconds to wait before retrying.

The rate limiter operates in-memory on the server — no Redis or external dependencies required.

IP Filtering

Allows or blocks requests based on the source IP, with CIDR range support.

Mode	Behavior
Disabled	No IP restrictions
Whitelist	Only IPs/ranges in the list are allowed
Blacklist	IPs/ranges in the list are blocked

List format: one IP or CIDR range per line. Examples:

192.168.1.10
10.0.0.0/8
172.16.0.0/12

IP-blocked requests return 403 Forbidden with reason ip_blacklist.

HMAC-SHA256 Signature

Verifies that each request body is signed with a shared secret. Designed for services that support payload signing (GitHub, Stripe, etc.).

Field	Description
Secret key	Shared secret key with the external service
Header	Header name containing the signature (default: X-Floogos-Signature)

The ⚡ button generates a random 32-byte hex key directly in the browser (Web Crypto API), without transmitting it to the server until saved.

Expected signature format:

sha256=<hmac_hex_of_body>

Requests without a signature or with an invalid signature return 403 Forbidden with reason signature_invalid.

Schedule Restrictions

Allows the webhook to only accept requests on specific days and times.

Field	Description
From / To	Time range in HH:MM format
Timezone	Timezone for evaluating the schedule (default: UTC)

Requests outside the schedule return 403 Forbidden with reason schedule_blocked.

---

Access Insights

The Insights page for a webhook is available at /webhooks/:id/insights and provides a complete analysis of access traffic.

Period Selector

The analysis period is configurable: 7, 14, 30, 60, or 90 days. When changed, all charts and tables update automatically.

KPI Cards (7 metrics)

Metric	Description
Total calls	Total requests in the period with daily sparkline
Allowed	Requests with status allowed
Blocked	Sum of blocked + rate_limited
Success rate	allowed / total × 100 with sparkline
Errors	Requests with status error (workflow execution failure)
Avg time	Average execution time in milliseconds
Peak time	Maximum recorded execution time in the period

Daily Volume Chart

Area chart showing the daily evolution of total requests (orange) and blocked requests (red) over the selected period.

Top 10 IPs

List of the 10 IPs with the highest call volume, showing:

• Progress bar relative to the maximum
• Total call count
• Blocked call count (if applicable)

Block Reasons

Distribution of blocks by reason with progress bars:

Reason	Description
Rate limit	Exceeded request limit for the window
IP blocked	IP on blacklist or not on whitelist
Invalid signature	Missing or incorrect HMAC header
Method not allowed	HTTP method not in the allowed list
Payload too large	Body exceeds the max_payload_bytes limit
Out of schedule	Request received outside configured hours
Execution error	Workflow threw an error during execution

HTTP Methods

Breakdown of requests by HTTP method (GET, POST, etc.) with relative percentage.

Prod vs Dev

Distribution of calls between the production endpoint (/webhooks/<hash>) and the development endpoint (/webhooks-dev/<hash>).

Access Log

Paginated table with the complete request history. Supports up to 100 rows per page.

Column	Description
Date	Request timestamp
IP	Source IP address
Method	GET / POST
Status	allowed (green), rate_limited (yellow), blocked / error (red)
Reason	Block reason if applicable
Code	HTTP response code
Duration	Workflow execution time in ms
Size	Payload size in KB
Environment	PROD or DEV

---

Response Codes

Security responses (before workflow execution)

These codes are returned when the security policy rejects the request, regardless of the environment (PROD or DEV):

Code	Reason
403	IP blocked, invalid signature, or out of schedule
405	HTTP method not allowed
413	Payload exceeds maximum size
429	Rate limit exceeded (includes retry_after)

Execution responses

The response body varies depending on the environment and the final node of the workflow:

Scenario	PROD	DEV
Ends with webresponse	Custom code, headers, and body	Same as PROD
Without webresponse — success	{"status": 200}	Full workflow result
Without webresponse — error	{"status": 500}	{"error": "error message"}

The production URL never exposes internal workflow data or plain-text error messages. For fully customized HTTP responses, use the webresponse node.

---

Best Practices

• Always assign a policy to webhooks receiving real external traffic.
• Use the DEV URL during development and testing to avoid contaminating production statistics.
• Review the access log regularly to detect suspicious IPs and adjust filtering lists.
• Enable HMAC when the external service supports it (Stripe, GitHub, Shopify) — it’s the most robust security layer.
• Combine rate limiting + IP whitelist for high-risk internal APIs.

See also

• Lock a resource with a key