Incoming Webhooks

Incoming webhooks allow external services to trigger actions in your NovaKit account. Create a unique URL that other services can POST to, triggering AI agents, generations, or custom workflows.

Use Cases

• Zapier/Make/n8n Integration: Trigger NovaKit from any automation platform
• CI/CD Pipelines: Generate release notes or summaries automatically
• Form Submissions: Process form data with AI agents
• Slack/Discord Commands: Trigger generations from chat platforms
• IoT Devices: Trigger actions from sensors or hardware
• CRM Events: Generate content when deals close or contacts are updated

How It Works

1. Create an incoming webhook in Dashboard → Settings → Integrations → Incoming
2. Configure the action (run agent, generate content, send notification)
3. Get your unique webhook URL and secret token
4. Send POST requests to trigger the action

Creating an Incoming Webhook

Via Dashboard

1. Go to Dashboard → Settings → Integrations → Incoming Webhooks
2. Click Create Webhook
3. Enter a name and unique slug (e.g., generate-summary)
4. Select the action type
5. Configure action-specific settings
6. Copy the URL and secret token (shown only once!)

Webhook URL Format

https://www.novakit.ai/api/webhooks/incoming/{slug}

Example: https://www.novakit.ai/api/webhooks/incoming/generate-summary

Action Types

1. Run Agent (run_agent)

Trigger an AI agent with dynamic input.

Configuration:

{
  "actionType": "run_agent",
  "actionConfig": {
    "agentId": "agent_abc123",
    "inputField": "message"
  }
}

Request:

curl -X POST https://www.novakit.ai/api/webhooks/incoming/my-agent \
  -H "Authorization: Bearer whsec_your_secret_token" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarize this customer feedback: Great product!"
  }'

Response:

{
  "success": true,
  "runId": "run_xyz789",
  "status": "started",
  "message": "Agent run started"
}

2. Trigger Generation (trigger_generation)

Start an image, video, or other generation job.

Configuration:

{
  "actionType": "trigger_generation",
  "actionConfig": {
    "tool": "image",
    "model": "fal-ai/flux/dev",
    "promptField": "prompt",
    "defaults": {
      "size": "1024x1024"
    }
  }
}

Request:

curl -X POST https://www.novakit.ai/api/webhooks/incoming/generate-image \
  -H "Authorization: Bearer whsec_your_secret_token" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A sunset over mountains"
  }'

Response:

{
  "success": true,
  "jobId": "job_abc123",
  "status": "pending",
  "message": "Generation started"
}

3. Send Notification (send_notification)

Send a notification to configured channels (email, Slack, Discord).

Configuration:

{
  "actionType": "send_notification",
  "actionConfig": {
    "channels": ["slack", "email"],
    "titleField": "subject",
    "messageField": "body"
  }
}

Request:

curl -X POST https://www.novakit.ai/api/webhooks/incoming/notify-team \
  -H "Authorization: Bearer whsec_your_secret_token" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "New Lead",
    "body": "John Doe just signed up for a demo"
  }'

4. Custom Action (custom)

Execute a custom workflow or chain of actions.

Configuration:

{
  "actionType": "custom",
  "actionConfig": {
    "workflow": "process-feedback",
    "mappings": {
      "input": "$.feedback",
      "metadata": "$.user"
    }
  }
}

Authentication

All incoming webhook requests require authentication via the secret token.

Bearer Token (Recommended)

curl -X POST https://www.novakit.ai/api/webhooks/incoming/my-webhook \
  -H "Authorization: Bearer whsec_your_secret_token" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

Header Token

curl -X POST https://www.novakit.ai/api/webhooks/incoming/my-webhook \
  -H "X-Webhook-Token: whsec_your_secret_token" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

Query Parameter (Not Recommended)

curl -X POST "https://www.novakit.ai/api/webhooks/incoming/my-webhook?token=whsec_your_secret_token" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

Rate Limiting

Each incoming webhook has its own rate limit to prevent abuse.

Limits by Plan

Rate Limit Headers

Responses include rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1703123456

Rate Limited Response

{
  "error": "Rate limit exceeded",
  "retryAfter": 30,
  "limit": 60,
  "remaining": 0
}

Status: 429 Too Many Requests

Error Responses

{
  "error": "unauthorized",
  "message": "Invalid or missing webhook token"
}

Request Logging

All incoming webhook requests are logged for debugging. View logs in: Dashboard → Settings → Integrations → Incoming Webhooks → [Webhook] → Logs

Logs include:

• Request timestamp
• Request headers (sensitive data redacted)
• Request body
• Response status
• Action result
• Duration

Integration Examples

Zapier

1. Create a new Zap
2. Add a trigger (e.g., "New Row in Google Sheets")
3. Add a Webhooks by Zapier action
4. Select POST
5. Enter your NovaKit webhook URL
6. Add header: Authorization: Bearer whsec_your_token
7. Map data fields to your webhook's expected format

Make (Integromat)

1. Create a new scenario
2. Add a trigger module
3. Add an HTTP > Make a request module
4. Configure:
   • URL: Your webhook URL
   • Method: POST
   • Headers: Authorization: Bearer whsec_your_token
   • Body type: JSON
   • Request content: Your payload

n8n

{
  "nodes": [
    {
      "parameters": {
        "url": "https://www.novakit.ai/api/webhooks/incoming/your-webhook",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "options": {
          "bodyContentType": "json"
        }
      },
      "name": "HTTP Request",
      "type": "n8n-nodes-base.httpRequest",
      "position": [450, 300]
    }
  ]
}

GitHub Actions

- name: Trigger NovaKit
  run: |
    curl -X POST https://www.novakit.ai/api/webhooks/incoming/release-notes \
      -H "Authorization: Bearer ${{ secrets.NOVAKIT_WEBHOOK_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d '{
        "version": "${{ github.ref_name }}",
        "changes": "${{ github.event.release.body }}"
      }'

Slack Slash Command

1. Create a Slack App
2. Add a Slash Command (e.g., /generate)
3. Set Request URL to your NovaKit webhook
4. In your webhook config, map Slack's text field to your prompt

Managing Webhooks

Regenerate Secret

If your secret is compromised:

1. Go to Dashboard → Incoming Webhooks
2. Click on the webhook
3. Click Regenerate Secret
4. Update the token in all integrations

Enable/Disable

Temporarily disable a webhook without deleting it:

# Via dashboard or API
PATCH /api/v1/incoming-webhooks/{id}
{ "enabled": false }

Delete

Permanently remove a webhook:

1. Go to Dashboard → Incoming Webhooks
2. Click on the webhook
3. Click Delete
4. Confirm deletion

Best Practices

1. Use Descriptive Slugs

Choose slugs that describe the action:

• ✅ generate-product-image
• ✅ process-customer-feedback
• ❌ webhook1
• ❌ test

2. Set Appropriate Rate Limits

Start with lower limits and increase as needed. This prevents runaway automation from exhausting your quota.

3. Monitor Usage

Check the dashboard regularly for:

• Error rates
• Usage patterns
• Unexpected activity

4. Validate Input

Use the inputField and promptField configs to specify which fields to use, preventing injection of unexpected data.

5. Test Before Production

Use the "Test" feature in the dashboard to verify your webhook works before connecting production systems.