Webhooks

Developer

What are Webhooks?

Webhooks are URLs that receive HTTP POST requests from external systems when certain events occur. In Prodgy, webhooks can be used to:

Trigger agents automatically based on external events
Receive notifications from integrated tools (Git, DevOps, communicators)
Integrate systems that need to send data to Prodgy in real time

Webhook Endpoint

Prodgy webhooks use custom paths:

POST /api/webhook/{custom_path}
Content-Type: application/json

{
  "event": "event_type",
  "data": { }
}

The custom_path is defined during webhook configuration and serves as a unique identifier.

Request Format

Field	Type	Description
Content-Type	Header	`application/json`
Method	HTTP	`POST`
Body	JSON	Event payload with structured data

Payload Example

{
  "event": "commit.pushed",
  "repository": "my-project",
  "branch": "main",
  "author": "dev@example.com",
  "timestamp": "2026-03-05T14:30:00Z",
  "data": {
    "commit_id": "abc123",
    "message": "feat: new feature"
  }
}

Response Format

Success

{
  "success": true,
  "message": "Webhook processed successfully",
  "data": { }
}

Error

{
  "success": false,
  "message": "Error description"
}

HTTP Status Codes

Code	Description
200	Webhook processed successfully
400	Invalid or malformed payload
404	Webhook path not found
500	Internal error processing the webhook

Communicator Webhooks

Prodgy receives webhooks from communication platforms for chat integration:

Slack / Google Chat

POST /api/communicator/webhook/{integration_base_id}
Content-Type: application/json

Microsoft Teams (Bot Framework)

POST /api/communicator/botframework/{integration_base_id}/messages
Content-Type: application/json

These endpoints are automatically configured when installing communicator integrations and do not require manual configuration.

Best Practices

Validate received data before processing — never blindly trust the payload
Respond quickly — return HTTP 200 as fast as possible and process asynchronously if needed
Implement retries — configure the system sending webhooks to retry on failure (5xx)
Use HTTPS in production to protect transmitted data
Monitor logs to identify failures and unprocessed events