Outgoing Webhooks

Outgoing webhooks allow you to receive real-time notifications when specific events occur in your Forge sites. This documentation covers all available webhook events, their payloads, and how to configure them.

Table of Contents

• Overview
• Supported Events
• Webhook Configuration
• Available Variables
• HTTP Methods
• Retry Logic
• Security Considerations
• Testing Webhooks
• Common Templates
• Examples

Overview

Forge webhooks are HTTP callbacks that send POST or GET requests to your specified URL when certain events occur. Each webhook can be configured with custom parameters and variables that get interpolated at runtime.

Key Features

• Real-time notifications: Receive instant updates when events occur
• Customizable payloads: Use variables to include dynamic data
• Multiple HTTP methods: Support for both GET and POST requests
• Automatic retries: Failed webhooks are retried up to 5 times
• Variable interpolation: Use {{variable_name}} syntax in parameters

Supported Events

Forge currently supports the following webhook events:

1. Deployment Success (deploy_success)

Triggered when a site deployment completes successfully.

When it fires:

• After a successful site deployment
• When a new version is deployed to your site
• After compilation and upload processes complete

Common use cases:

• Notify your team about successful deployments
• Trigger external CI/CD processes
• Update deployment status in external systems

2. Deployment Failure (deploy_failure)

Triggered when a site deployment fails.

When it fires:

• When deployment process encounters an error
• When compilation fails
• When upload process fails
• When any deployment step fails

Common use cases:

• Alert your team about failed deployments
• Trigger rollback procedures
• Log deployment failures for analysis

3. Form Submission (form_submission)

Triggered when a form on your site receives a submission. This powerful webhook type allows you to target specific forms and access rich form data with flexible filtering options.

When it fires:

• When a user submits a form on your site
• After form data is validated and saved
• Only for selected forms (if form-specific configuration is used)

Common use cases:

• Send form data to external CRM systems
• Trigger email notifications for new submissions
• Integrate with marketing automation tools
• Log form submissions to external databases
• Notify your team via Slack or Discord
• Create tickets in help desk systems

Form-Specific Configuration

When you choose "Form submission" as your event type, you'll see additional configuration options:

4. Plugin Analysis Complete (plugin_analysis_complete)

Triggered when the security analysis of your site's plugins is completed.

When it fires:

• After the system analyzes your site's JavaScript and HTML files
• When security assessment is complete

Common use cases:

• Receive security analysis reports
• Trigger security monitoring systems
• Alert about potential security issues

Webhook Configuration

Required Fields

When creating a webhook, you must provide:

• Event: The type of event to listen for
• URL: The endpoint where the webhook will be sent
• HTTP Method: GET or POST
• Parameters (optional): Custom key-value pairs to include in the request

URL Format

Webhooks support both HTTP and HTTPS URLs:

https://your-domain.com/webhook-endpoint
http://your-domain.com/webhook-endpoint

Note: URLs must not be from getforge.com domains for security reasons.

Parameter Format

Parameters are specified as key-value pairs, one per line:

key1=value1
key2=value2
key3=value3

You can use variables in your parameters using the {{variable_name}} syntax:

site_name={{domain}}
version={{version_id}}
deployment_time={{timestamp}}

Available Variables

The following variables are available for use in webhook parameters:

Site Variables

Form Submission Variables

When a form is submitted, you have access to rich form data through various variables. The available variables depend on whether you've selected a specific form or are monitoring all forms.

Form Metadata Variables

These variables are available for all form submission webhooks:

Form Field Variables

When you select a specific form, you'll also have access to individual form field variables:

Variable Access and Copying

When creating a form submission webhook, you'll see an "Available Variables" section with:

Plugin Analysis Variables

For plugin_analysis_complete events:

HTTP Methods

GET Requests

When using GET method, parameters are appended to the URL as query parameters:

https://your-domain.com/webhook?site_name=my-site&version=12345

POST Requests

When using POST method, parameters are sent in the request body as form data:

Content-Type: application/x-www-form-urlencoded

site_name=my-site&version=12345&status=success

Retry Logic

If a webhook fails to deliver, Forge will automatically retry:

• Maximum retries: 5 attempts
• Retry interval: Exponential backoff
• Failure conditions: Network errors, timeout, or non-2xx responses

After 5 failed attempts, the webhook will be marked as failed and no further retries will be attempted.

Security Considerations

URL Validation

• Webhooks cannot be sent to getforge.com domains
• URLs must be properly formatted HTTP or HTTPS endpoints
• Invalid URLs will be rejected during webhook creation

Best Practices

1. Use HTTPS: Always use HTTPS endpoints for production webhooks
2. Validate signatures: Implement signature validation in your webhook handler
3. Handle duplicates: Your webhook endpoint should be idempotent
4. Timeout handling: Ensure your endpoint responds within 30 seconds
5. Error handling: Return appropriate HTTP status codes

Testing Webhooks

Forge provides built-in testing capabilities to help you verify your webhook configurations before they go live. This is especially useful for form submission webhooks where you can test with real form data.

Testing Form Submission Webhooks

Form submission webhooks can be tested in two ways:

Testing Process

1. Access Testing: Click the "Test" button next to your webhook in the list
2. Choose Test Type: Select "Sample Data" or "Form Submission"
3. Select Data: If using Form Submission, select a specific submission from the dropdown
4. Review Payload: Preview the webhook payload before sending
5. Run Test: Click "Run Test" to send the webhook
6. View Results: Check the response status and content

Testing Other Webhook Types

For non-form submission webhooks, testing uses sample data that represents typical event payloads:

• Deployment webhooks: Sample deployment data with site information
• Plugin analysis webhooks: Sample analysis results
• All webhooks: Include relevant metadata and variables

Testing Best Practices

Common Templates

When creating a form submission webhook, you'll see pre-built templates for popular integrations. These templates provide a quick starting point for common use cases.

Available Templates

payload={"text": "New form submission received for {{form_human_name}} on {{form_submitted_at}}", "channel": "#general", "username": "Forge Bot", "icon_emoji": ":rocket:"}

content = New {{form_human_name}} form submission received!
username = Forge Bot
avatar_url = https://getforge.com/logo.png

to = admin@example.com
subject = New {{form_human_name}} form submission
body = A new form submission has been received for {{form_human_name}}.
form_data = {{form_fields}}

action = form_submission
form_name = {{form_human_name}}
form_data = {{form_fields}}
timestamp = {{form_submitted_at}}

event_type = form_submission
form_id = {{form_id}}
form_name = {{form_human_name}}
data = {{form_fields}}

Using Templates

To use a template when creating a form submission webhook:

1. Select "Form submission" as your event type
2. Choose your form (optional)
3. Browse the available templates in the horizontal row
4. Click on a template to apply it
5. Customize the template parameters as needed
6. Add your webhook URL and save

Customizing Templates

All templates can be customized to fit your specific needs:

• Modify parameters: Change any parameter values
• Add variables: Include additional form variables
• Update formatting: Adjust message formatting and styling
• Add conditions: Use conditional logic based on form data

Examples

Example 1: Deployment Success Notification

Event: deploy_success
URL: https://your-slack-webhook.com/deployments
Method: POST
Parameters:

channel=#deployments
text=Deployment successful for {{domain}} (Version {{version_id}})
color=good

Example 2: Form Submission to CRM

Event: form_submission
URL: https://api.your-crm.com/leads
Method: POST
Parameters:

api_key=your-api-key
name={{name}}
email={{email}}
phone={{phone}}
source={{domain}}

Example 3: Deployment Failure Alert

Event: deploy_failure
URL: https://your-monitoring-service.com/alerts
Method: POST
Parameters:

alert_type=deployment_failure
site={{domain}}
severity=high
message=Deployment failed for {{domain}}

Example 4: File Change Tracking

Event: deploy_success
URL: https://your-analytics.com/track
Method: GET
Parameters:

event=deployment
site={{domain}}
added_files={{added_files}}
modified_files={{modified_files}}
deleted_files={{deleted_files}}

Example 5: Slack Form Notification

Event: form_submission
URL: https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK
Method: POST
Content-Type: application/json
Payload:

{
  "channel": "#form-submissions",
  "username": "Forge Forms Bot",
  "icon_emoji": ":inbox_tray:",
  "attachments": [
    {
      "color": "#36a64f",
      "title": "New Form Submission: {{form_name}}",
      "title_link": "https://{{domain}}",
      "fields": [
        {
          "title": "Form Name",
          "value": "{{form_name}}",
          "short": true
        },
        {
          "title": "Submission ID",
          "value": "{{form_datum_id}}",
          "short": true
        },
        {
          "title": "Domain",
          "value": "{{domain}}",
          "short": true
        },
        {
          "title": "Timestamp",
          "value": "{{timestamp}}",
          "short": true
        }
      ],
      "footer": "Forge Forms",
      "footer_icon": "https://platform.slack-edge.com/img/default_application_icon.png",
      "ts": "{{timestamp_unix}}"
    }
  ]
}

Enhanced Slack Payload with Form Fields

For a more detailed notification that includes specific form fields:

{
  "channel": "#leads",
  "username": "Lead Capture Bot",
  "icon_emoji": ":rocket:",
  "attachments": [
    {
      "color": "#36a64f",
      "title": "🎯 New Lead: {{name}}",
      "title_link": "https://{{domain}}",
      "text": "A new lead has been captured from your website!",
      "fields": [
        {
          "title": "Name",
          "value": "{{name}}",
          "short": true
        },
        {
          "title": "Email",
          "value": "{{email}}",
          "short": true
        },
        {
          "title": "Phone",
          "value": "{{phone}}",
          "short": true
        },
        {
          "title": "Company",
          "value": "{{company}}",
          "short": true
        },
        {
          "title": "Message",
          "value": "{{message}}",
          "short": false
        },
        {
          "title": "Source",
          "value": "{{domain}}",
          "short": true
        },
        {
          "title": "Submission ID",
          "value": "{{form_datum_id}}",
          "short": true
        }
      ],
      "actions": [
        {
          "type": "button",
          "text": "View in Forge",
          "url": "https://app.getforge.com/sites/{{domain}}/forms"
        }
      ],
      "footer": "Forge Forms",
      "footer_icon": "https://platform.slack-edge.com/img/default_application_icon.png",
      "ts": "{{timestamp_unix}}"
    }
  ]
}

Simple Text-Based Slack Notification

For a simpler text-based notification:

{
  "channel": "#notifications",
  "text": "📝 New form submission received!\n\n*Form:* {{form_name}}\n*From:* {{name}} ({{email}})\n*Message:* {{message}}\n*Source:* {{domain}}\n*ID:* {{form_datum_id}}",
  "username": "Form Bot",
  "icon_emoji": ":memo:"
}

Slack Block Kit Format (Modern)

Using Slack's newer Block Kit format for better formatting:

{
  "channel": "#form-submissions",
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "📝 New Form Submission",
        "emoji": true
      }
    },
    {
      "type": "section",
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*Form:*\n{{form_name}}"
        },
        {
          "type": "mrkdwn",
          "text": "*Submitted:*\n{{timestamp}}"
        }
      ]
    },
    {
      "type": "section",
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*Name:*\n{{name}}"
        },
        {
          "type": "mrkdwn",
          "text": "*Email:*\n{{email}}"
        }
      ]
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Message:*\n{{message}}"
      }
    },
    {
      "type": "context",
      "elements": [
        {
          "type": "mrkdwn",
          "text": "🌐 {{domain}} • ID: {{form_datum_id}}"
        }
      ]
    },
    {
      "type": "actions",
      "elements": [
        {
          "type": "button",
          "text": {
            "type": "plain_text",
            "text": "View in Forge",
            "emoji": true
          },
          "url": "https://app.getforge.com/sites/{{domain}}/forms"
        }
      ]
    }
  ]
}

Troubleshooting

Common Issues

1. Webhook not firing: Check that the event type matches exactly
2. URL rejected: Ensure the URL is not from a getforge.com domain
3. Parameters not interpolated: Verify variable names are correct and wrapped in {{}}
4. Retries failing: Check your endpoint's availability and response times

Debugging Tips

1. Test your endpoint: Use a service like webhook.site to test your webhook URL
2. Check logs: Monitor your webhook endpoint logs for incoming requests
3. Validate parameters: Ensure your endpoint can handle the parameter format
4. Test variables: Create a simple webhook to test variable interpolation

Support

If you encounter issues with webhooks:

1. Check the webhook configuration in your Forge dashboard
2. Verify your endpoint is accessible and responding correctly
3. Review the webhook logs for error messages
4. Contact Forge support with specific error details