Create webhook

http
POST /projects/{project_reference}/webhooks

Create a webhook when an external service must start an agent, task or workflow run, or when its deliveries must only be stored as webhook events; returns the webhook and its secret, which is shown only once. Requires project.agents.write.

Servers

json
[
  {
    "url": "https://api.veryfront.com"
  }
]

Authentication

json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyAuth": []
  }
]
json
{
  "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT or API Key",
    "description": "Use a JWT bearer token or a Veryfront API key in the `Authorization` header."
  },
  "apiKeyAuth": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key",
    "description": "Alternative API key header for `vf_<prefix>_<secret>` tokens."
  }
}

Parameters

NameLocationRequiredDescription
project_referencepathYes

Parameter contracts

json
[
  {
    "schema": {
      "type": "string",
      "minLength": 1
    },
    "required": true,
    "name": "project_reference",
    "in": "path"
  }
]

Request body

json
{
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "description": "Webhook name, 1-120 characters."
          },
          "target": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "agent",
                  "task",
                  "workflow",
                  "event"
                ],
                "description": "Target kind invoked or stored by the webhook."
              },
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "description": "Target identifier: agent id, task target, workflow id, or event for store-only webhooks."
              },
              "conversation_mode": {
                "type": "string",
                "enum": [
                  "create_new",
                  "existing",
                  "none"
                ],
                "description": "Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation. Agent targets run headlessly by default; create_new or existing creates or appends a conversation message. Agent targets with conversation mode create_new or existing also require project.conversations.write."
              },
              "conversation_id": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uuid",
                "description": "Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."
              }
            },
            "required": [
              "kind",
              "id"
            ],
            "additionalProperties": false,
            "description": "Target invoked by a webhook definition."
          },
          "prompt_template": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20000,
            "description": "Prompt template for run targets: required unless target.kind is event, where it is not supported."
          },
          "event_filter": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "all",
                  "any"
                ],
                "description": "Whether all or any filter conditions must match."
              },
              "conditions": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "path": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 255,
                      "description": "Dot path in the incoming payload, for example action or pull_request.state."
                    },
                    "operator": {
                      "type": "string",
                      "enum": [
                        "equals",
                        "not_equals",
                        "in",
                        "exists",
                        "contains"
                      ],
                      "description": "Comparison operator."
                    },
                    "value": {
                      "description": "Comparison value for operators that require one."
                    }
                  },
                  "required": [
                    "path",
                    "operator"
                  ],
                  "additionalProperties": false
                },
                "maxItems": 50,
                "description": "Filter conditions applied before webhook work is created."
              }
            },
            "required": [
              "mode",
              "conditions"
            ],
            "additionalProperties": false,
            "description": "Optional incoming event filter. Missing, null, or empty conditions accept every event."
          }
        },
        "required": [
          "name",
          "target"
        ],
        "additionalProperties": false
      }
    }
  }
}

Responses

201

Created webhook

json
{
  "description": "Created webhook",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "webhook": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "The webhook id. Pass it as webhook_id to the other webhook operations."
              },
              "project_id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "source": {
                "type": "string",
                "enum": [
                  "webhook"
                ]
              },
              "target": {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "agent",
                      "task",
                      "workflow",
                      "event"
                    ],
                    "description": "Target kind invoked or stored by the webhook."
                  },
                  "id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "description": "Target identifier: agent id, task target, workflow id, or event for store-only webhooks."
                  },
                  "conversation_mode": {
                    "type": "string",
                    "enum": [
                      "create_new",
                      "existing",
                      "none"
                    ],
                    "description": "Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation. Agent targets run headlessly by default; create_new or existing creates or appends a conversation message. Agent targets with conversation mode create_new or existing also require project.conversations.write."
                  },
                  "conversation_id": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uuid",
                    "description": "Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              },
              "prompt_template": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "event_filter": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "mode": {
                    "type": "string",
                    "enum": [
                      "all",
                      "any"
                    ],
                    "description": "Whether all or any filter conditions must match."
                  },
                  "conditions": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "path": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 255,
                          "description": "Dot path in the incoming payload, for example action or pull_request.state."
                        },
                        "operator": {
                          "type": "string",
                          "enum": [
                            "equals",
                            "not_equals",
                            "in",
                            "exists",
                            "contains"
                          ],
                          "description": "Comparison operator."
                        },
                        "value": {
                          "description": "Comparison value for operators that require one."
                        }
                      },
                      "required": [
                        "path",
                        "operator"
                      ],
                      "additionalProperties": false
                    },
                    "maxItems": 50,
                    "description": "Filter conditions applied before webhook work is created."
                  }
                },
                "required": [
                  "mode",
                  "conditions"
                ],
                "additionalProperties": false,
                "description": "Optional incoming event filter. Missing, null, or empty conditions accept every event."
              },
              "status": {
                "type": "string",
                "enum": [
                  "draft",
                  "enabled",
                  "disabled"
                ]
              },
              "runtime_target_kind": {
                "type": "string",
                "enum": [
                  "main_branch",
                  "environment",
                  "preview_branch"
                ]
              },
              "runtime_target_environment_id": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uuid"
              },
              "runtime_target_branch_id": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uuid"
              },
              "definition_source": {
                "type": "string",
                "enum": [
                  "manual",
                  "source"
                ]
              },
              "source_trigger_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "source_path": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "source_hash": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "ingress_id": {
                "type": "string",
                "description": "The public id in webhook_url that external senders post to."
              },
              "webhook_url": {
                "type": "string"
              },
              "created_by_user_id": {
                "type": "string",
                "format": "uuid"
              },
              "enabled_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "disabled_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "disabled_reason": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "created_at": {
                "type": "string"
              },
              "updated_at": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "project_id",
              "name",
              "source",
              "target",
              "prompt_template",
              "event_filter",
              "status",
              "runtime_target_kind",
              "runtime_target_environment_id",
              "runtime_target_branch_id",
              "definition_source",
              "source_trigger_id",
              "source_path",
              "source_hash",
              "ingress_id",
              "webhook_url",
              "created_by_user_id",
              "enabled_at",
              "disabled_at",
              "disabled_reason",
              "created_at",
              "updated_at"
            ]
          },
          "webhook_secret": {
            "type": "string",
            "description": "Secret for the X-Veryfront-Webhook-Secret header. Returned only once, on create; store it now."
          }
        },
        "required": [
          "webhook",
          "webhook_secret"
        ]
      }
    }
  }
}

400

invalid_input: invalid body or parameters

json
{
  "description": "invalid_input: invalid body or parameters",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

401

unauthenticated

json
{
  "description": "unauthenticated",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

403

forbidden: a project member without the required capability

json
{
  "description": "forbidden: a project member without the required capability",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

404

not_found: project or webhook not found or not visible

json
{
  "description": "not_found: project or webhook not found or not visible",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

500

internal

json
{
  "description": "internal",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

503

internal: authentication state is temporarily unavailable and the request was not processed; retry shortly

json
{
  "description": "internal: authentication state is temporarily unavailable and the request was not processed; retry shortly",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Referenced contracts

components/schemas/Problem

json
{
  "type": "object",
  "properties": {
    "cause": {
      "type": "string",
      "enum": [
        "schedule_concurrency_forbidden",
        "schedule_fire_in_progress",
        "schedule_run_limit_reached"
      ],
      "description": "Schedule admission refusal."
    },
    "idempotency": {
      "type": "object",
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "in_progress",
            "payload_mismatch",
            "outcome_unknown"
          ]
        },
        "operation": {
          "type": "string",
          "minLength": 1
        },
        "retryable": {
          "type": "boolean"
        },
        "retry_after_seconds": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0
        },
        "expires_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "recovery": {
          "type": "object",
          "properties": {
            "available": {
              "type": "boolean"
            },
            "description": {
              "type": "string"
            },
            "resource_url": {
              "type": "string"
            }
          },
          "required": [
            "available",
            "description"
          ]
        }
      },
      "required": [
        "state",
        "operation",
        "retryable",
        "retry_after_seconds",
        "expires_at"
      ],
      "description": "Replay status, retry timing, and recovery lookup."
    },
    "type": {
      "type": "string",
      "description": "URI reference identifying the problem type",
      "example": "https://api.veryfront.com/errors/validation-failed"
    },
    "title": {
      "type": "string",
      "description": "Short human-readable summary of the problem",
      "example": "Validation Failed"
    },
    "status": {
      "type": "integer",
      "minimum": 100,
      "maximum": 599,
      "description": "HTTP status code",
      "example": 400
    },
    "code": {
      "type": "string",
      "description": "Stable machine-readable error code",
      "example": "RUN_INVALID_INPUT"
    },
    "detail": {
      "type": "string",
      "description": "Human-readable explanation specific to this occurrence",
      "example": "The 'email' field must be a valid email address"
    },
    "instance": {
      "type": "string",
      "description": "URI reference identifying the specific occurrence",
      "example": "/projects/my-project/members"
    },
    "slug": {
      "type": "string",
      "description": "Stable identifier for the problem type",
      "example": "validation-failed"
    },
    "category": {
      "type": "string",
      "enum": [
        "AUTH",
        "RESOURCE",
        "VALIDATION",
        "DATABASE",
        "SUBSCRIPTION",
        "INTEGRATION",
        "INTERNAL"
      ],
      "description": "API error category",
      "example": "VALIDATION"
    },
    "suggestion": {
      "type": "string",
      "description": "Suggested action to resolve the problem",
      "example": "Check the request body and query parameters against the API documentation."
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Field path that caused the error",
            "example": "email"
          },
          "message": {
            "type": "string",
            "description": "Error message for this field",
            "example": "Invalid email format"
          },
          "code": {
            "type": "string",
            "description": "Error code for this field",
            "example": "INVALID_FORMAT"
          }
        },
        "required": [
          "field",
          "message"
        ]
      },
      "description": "Detailed field-level errors for validation failures"
    }
  },
  "required": [
    "type",
    "title",
    "status"
  ]
}

Operation contract

json
{
  "operationId": "createWebhook",
  "tags": [
    "execution/Triggers/Webhooks"
  ],
  "summary": "Create webhook",
  "description": "Create a webhook when an external service must start an agent, task or workflow run, or when its deliveries must only be stored as webhook events; returns the webhook and its secret, which is shown only once. Requires project.agents.write.",
  "parameters": [
    {
      "schema": {
        "type": "string",
        "minLength": 1
      },
      "required": true,
      "name": "project_reference",
      "in": "path"
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120,
              "description": "Webhook name, 1-120 characters."
            },
            "target": {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "agent",
                    "task",
                    "workflow",
                    "event"
                  ],
                  "description": "Target kind invoked or stored by the webhook."
                },
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128,
                  "description": "Target identifier: agent id, task target, workflow id, or event for store-only webhooks."
                },
                "conversation_mode": {
                  "type": "string",
                  "enum": [
                    "create_new",
                    "existing",
                    "none"
                  ],
                  "description": "Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation. Agent targets run headlessly by default; create_new or existing creates or appends a conversation message. Agent targets with conversation mode create_new or existing also require project.conversations.write."
                },
                "conversation_id": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "uuid",
                  "description": "Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."
                }
              },
              "required": [
                "kind",
                "id"
              ],
              "additionalProperties": false,
              "description": "Target invoked by a webhook definition."
            },
            "prompt_template": {
              "type": "string",
              "minLength": 1,
              "maxLength": 20000,
              "description": "Prompt template for run targets: required unless target.kind is event, where it is not supported."
            },
            "event_filter": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "mode": {
                  "type": "string",
                  "enum": [
                    "all",
                    "any"
                  ],
                  "description": "Whether all or any filter conditions must match."
                },
                "conditions": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "path": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "description": "Dot path in the incoming payload, for example action or pull_request.state."
                      },
                      "operator": {
                        "type": "string",
                        "enum": [
                          "equals",
                          "not_equals",
                          "in",
                          "exists",
                          "contains"
                        ],
                        "description": "Comparison operator."
                      },
                      "value": {
                        "description": "Comparison value for operators that require one."
                      }
                    },
                    "required": [
                      "path",
                      "operator"
                    ],
                    "additionalProperties": false
                  },
                  "maxItems": 50,
                  "description": "Filter conditions applied before webhook work is created."
                }
              },
              "required": [
                "mode",
                "conditions"
              ],
              "additionalProperties": false,
              "description": "Optional incoming event filter. Missing, null, or empty conditions accept every event."
            }
          },
          "required": [
            "name",
            "target"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Created webhook",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "webhook": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "The webhook id. Pass it as webhook_id to the other webhook operations."
                  },
                  "project_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string"
                  },
                  "source": {
                    "type": "string",
                    "enum": [
                      "webhook"
                    ]
                  },
                  "target": {
                    "type": "object",
                    "properties": {
                      "kind": {
                        "type": "string",
                        "enum": [
                          "agent",
                          "task",
                          "workflow",
                          "event"
                        ],
                        "description": "Target kind invoked or stored by the webhook."
                      },
                      "id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128,
                        "description": "Target identifier: agent id, task target, workflow id, or event for store-only webhooks."
                      },
                      "conversation_mode": {
                        "type": "string",
                        "enum": [
                          "create_new",
                          "existing",
                          "none"
                        ],
                        "description": "Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation. Agent targets run headlessly by default; create_new or existing creates or appends a conversation message. Agent targets with conversation mode create_new or existing also require project.conversations.write."
                      },
                      "conversation_id": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "format": "uuid",
                        "description": "Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case."
                      }
                    },
                    "required": [
                      "kind",
                      "id"
                    ],
                    "additionalProperties": false
                  },
                  "prompt_template": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "event_filter": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "properties": {
                      "mode": {
                        "type": "string",
                        "enum": [
                          "all",
                          "any"
                        ],
                        "description": "Whether all or any filter conditions must match."
                      },
                      "conditions": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "path": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 255,
                              "description": "Dot path in the incoming payload, for example action or pull_request.state."
                            },
                            "operator": {
                              "type": "string",
                              "enum": [
                                "equals",
                                "not_equals",
                                "in",
                                "exists",
                                "contains"
                              ],
                              "description": "Comparison operator."
                            },
                            "value": {
                              "description": "Comparison value for operators that require one."
                            }
                          },
                          "required": [
                            "path",
                            "operator"
                          ],
                          "additionalProperties": false
                        },
                        "maxItems": 50,
                        "description": "Filter conditions applied before webhook work is created."
                      }
                    },
                    "required": [
                      "mode",
                      "conditions"
                    ],
                    "additionalProperties": false,
                    "description": "Optional incoming event filter. Missing, null, or empty conditions accept every event."
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "draft",
                      "enabled",
                      "disabled"
                    ]
                  },
                  "runtime_target_kind": {
                    "type": "string",
                    "enum": [
                      "main_branch",
                      "environment",
                      "preview_branch"
                    ]
                  },
                  "runtime_target_environment_id": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uuid"
                  },
                  "runtime_target_branch_id": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uuid"
                  },
                  "definition_source": {
                    "type": "string",
                    "enum": [
                      "manual",
                      "source"
                    ]
                  },
                  "source_trigger_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "source_path": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "source_hash": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "ingress_id": {
                    "type": "string",
                    "description": "The public id in webhook_url that external senders post to."
                  },
                  "webhook_url": {
                    "type": "string"
                  },
                  "created_by_user_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "enabled_at": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "disabled_at": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "disabled_reason": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "created_at": {
                    "type": "string"
                  },
                  "updated_at": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "project_id",
                  "name",
                  "source",
                  "target",
                  "prompt_template",
                  "event_filter",
                  "status",
                  "runtime_target_kind",
                  "runtime_target_environment_id",
                  "runtime_target_branch_id",
                  "definition_source",
                  "source_trigger_id",
                  "source_path",
                  "source_hash",
                  "ingress_id",
                  "webhook_url",
                  "created_by_user_id",
                  "enabled_at",
                  "disabled_at",
                  "disabled_reason",
                  "created_at",
                  "updated_at"
                ]
              },
              "webhook_secret": {
                "type": "string",
                "description": "Secret for the X-Veryfront-Webhook-Secret header. Returned only once, on create; store it now."
              }
            },
            "required": [
              "webhook",
              "webhook_secret"
            ]
          }
        }
      }
    },
    "400": {
      "description": "invalid_input: invalid body or parameters",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "401": {
      "description": "unauthenticated",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "403": {
      "description": "forbidden: a project member without the required capability",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "404": {
      "description": "not_found: project or webhook not found or not visible",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "500": {
      "description": "internal",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "503": {
      "description": "internal: authentication state is temporarily unavailable and the request was not processed; retry shortly",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  },
  "x-documentation-source-tag": "Webhooks",
  "x-canonical-documentation": {
    "domain": "execution",
    "resource": "Triggers",
    "subgroup": "Webhooks",
    "name": "Create webhook",
    "description": "Create a webhook when an external service must start an agent, task or workflow run, or when its deliveries must only be stored as webhook events; returns the webhook and its secret, which is shown only once. Requires project.agents.write.",
    "operationId": "createWebhook"
  },
  "x-mint": {
    "href": "/cloud/rest/api-reference/execution-triggers-webhooks/create-webhook"
  }
}