Create a webhook
POST/v1/webhooks
This route allows you to create a webhook in your Port organization. You can also create it via the connectors page of your Port account.
To learn more about webhooks, check out the documentation.
Request
Request body schema (JSON)
{
"title": "Body",
"body": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"identifier": {
"type": "string",
"maxLength": 30,
"description": "The identifier of the webhook."
},
"title": {
"type": "string",
"maxLength": 30,
"description": "The title of the webhook, which will be displayed in the [connectors page](https://app.port.io/settings/data-sources) of your Port account."
},
"description": {
"type": "string",
"maxLength": 200,
"description": "A description for the webhook."
},
"icon": {
"type": "string",
"description": "The icon of the webhook."
},
"mappings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"oneOf": [
{
"title": "Advanced create",
"description": "If the operation is `create`, the [entity JSON](https://docs.port.io/context-lake/ingestion/ingest-data-into-port/native-integrations/overview/#json-structure) properties must be provided. For example:\n```json\n{\n \"operation\": \"create\",\n \"blueprint\": \"blueprint_identifier\",\n \"filter\": \"true\",\n \"itemsToParse\": \"true\",\n \"entity\": {\n \"identifier\": \"new-webhook\",\n \"title\": \"MyNewWebhook\",\n \"icon\": \"webhook\",\n \"team\": [],\n \"properties\": {\n \"content\": \"my content\"\n },\n \"relations\": {}\n }\n}\n```",
"enum": [
"create"
]
},
{
"type": "object",
"title": "Create",
"properties": {
"type": {
"enum": [
"create"
]
}
},
"required": [
"type"
],
"additionalProperties": false
},
{
"title": "Delete",
"description": "If the selected operation is `delete`, a blueprint identifier, and entity identifier must be provided, for example:\n```json\n{\n \"operation\": \"delete\",\n \"filter\": \"true\",\n \"itemsToParse\": \"true\",\n \"blueprint\": \"blueprint_identifier\",\n \"entity\": {\n \"identifier\": \"entity_identifier\"\n }\n}\n```",
"enum": [
"delete"
]
},
{
"type": "object",
"title": "Advanced delete",
"properties": {
"type": {
"enum": [
"delete"
]
},
"deleteDependents": {
"type": "boolean"
}
},
"required": [
"type"
],
"additionalProperties": false
}
],
"description": "If the selected operation is `delete`, a blueprint identifier, and entity identifier must be provided. If the operation is `create`, the [entity JSON](https://docs.port.io/context-lake/ingestion/ingest-data-into-port/native-integrations/overview/#json-structure) properties must be provided."
}
},
"if": {
"properties": {
"operation": {
"oneOf": [
{
"title": "Delete",
"description": "If the selected operation is `delete`, a blueprint identifier, and entity identifier must be provided, for example:\n```json\n{\n \"operation\": \"delete\",\n \"filter\": \"true\",\n \"itemsToParse\": \"true\",\n \"blueprint\": \"blueprint_identifier\",\n \"entity\": {\n \"identifier\": \"entity_identifier\"\n }\n}\n```",
"enum": [
"delete"
]
},
{
"type": "object",
"title": "Advanced delete",
"properties": {
"type": {
"enum": [
"delete"
]
},
"deleteDependents": {
"type": "boolean"
}
},
"required": [
"type"
],
"additionalProperties": false
}
]
}
},
"required": [
"operation"
]
},
"then": {
"properties": {
"operation": {
"oneOf": [
{
"title": "Delete",
"description": "If the selected operation is `delete`, a blueprint identifier, and entity identifier must be provided, for example:\n```json\n{\n \"operation\": \"delete\",\n \"filter\": \"true\",\n \"itemsToParse\": \"true\",\n \"blueprint\": \"blueprint_identifier\",\n \"entity\": {\n \"identifier\": \"entity_identifier\"\n }\n}\n```",
"enum": [
"delete"
]
},
{
"type": "object",
"title": "Advanced delete",
"properties": {
"type": {
"enum": [
"delete"
]
},
"deleteDependents": {
"type": "boolean"
}
},
"required": [
"type"
],
"additionalProperties": false
}
]
},
"blueprint": {
"type": "string",
"description": "The identifier of the blueprint to map the data into."
},
"filter": {
"type": "string",
"description": "A `jq` query used to filter exactly which payloads sent to the webhook are processed. If set to `\"true\"`, all payloads will be processed."
},
"itemsToParse": {
"type": "string",
"description": "A `jq` query that evaluates to an array of items, used to create multiple entities from a single webhook event."
},
"entity": {
"type": "object",
"properties": {
"identifier": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"identifier"
]
}
},
"required": [
"blueprint",
"entity"
],
"additionalProperties": true
},
"else": {
"properties": {
"operation": {
"oneOf": [
{
"title": "Advanced create",
"description": "If the operation is `create`, the [entity JSON](https://docs.port.io/context-lake/ingestion/ingest-data-into-port/native-integrations/overview/#json-structure) properties must be provided. For example:\n```json\n{\n \"operation\": \"create\",\n \"blueprint\": \"blueprint_identifier\",\n \"filter\": \"true\",\n \"itemsToParse\": \"true\",\n \"entity\": {\n \"identifier\": \"new-webhook\",\n \"title\": \"MyNewWebhook\",\n \"icon\": \"webhook\",\n \"team\": [],\n \"properties\": {\n \"content\": \"my content\"\n },\n \"relations\": {}\n }\n}\n```",
"enum": [
"create"
]
},
{
"type": "object",
"title": "Create",
"properties": {
"type": {
"enum": [
"create"
]
}
},
"required": [
"type"
],
"additionalProperties": false
}
]
},
"blueprint": {
"type": "string",
"description": "The identifier of the blueprint to map the data into."
},
"filter": {
"type": "string",
"description": "A `jq` query used to filter exactly which payloads sent to the webhook are processed. If set to `\"true\"`, all payloads will be processed."
},
"itemsToParse": {
"type": "string",
"description": "A `jq` query that evaluates to an array of items, used to create multiple entities from a single webhook event."
},
"entity": {
"type": "object",
"description": "An object defining how to map the data from the webhook payload into Port entities.",
"properties": {
"identifier": {
"oneOf": [
{
"type": "string",
"description": "A `jq` expression used to get data from the webhook payload, to be used as an identifier for the entity."
},
{
"type": "object",
"properties": {
"combinator": {
"type": "string"
},
"rules": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"additionalProperties": false,
"required": [
"combinator",
"rules"
]
}
]
},
"title": {
"type": "string",
"description": "A `jq` expression used to get data from the webhook payload, to be used as the title of the entity."
},
"icon": {
"type": "string",
"description": "The icon of the entity."
},
"team": {
"oneOf": [
{
"type": "string"
},
{
"type": "object",
"properties": {
"combinator": {
"type": "string"
},
"rules": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"additionalProperties": false,
"required": [
"combinator",
"rules"
]
}
]
},
"properties": {
"type": "object",
"description": "An object containing the properties of the entity and their values. For more information and examples, check out the [documentation](https://docs.port.io/context-lake/ingestion/ingest-data-into-port/webhook/ingest-via-webhooks-overview).",
"propertyNames": {
"type": "string"
}
},
"relations": {
"type": "object",
"description": "An object containing the relations of the entity and their values. For more information and examples, check out the [documentation](https://docs.port.io/context-lake/ingestion/ingest-data-into-port/webhook/ingest-via-webhooks-overview).",
"propertyNames": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"identifier"
]
}
},
"required": [
"blueprint",
"entity"
],
"additionalProperties": false
}
},
"description": "The mapping definitions used to map the data from the webhook into Port entities. For more information and examples, check out the [documentation](https://docs.port.io/context-lake/ingestion/ingest-data-into-port/webhook/ingest-via-webhooks-overview)."
},
"enabled": {
"type": "boolean",
"default": true,
"description": "Determines whether the webhook is active or not. If `false`, any incoming events will be dropped."
},
"security": {
"type": "object",
"properties": {
"secret": {
"type": "string",
"nullable": true
},
"signatureHeaderName": {
"type": "string",
"nullable": true
},
"signatureAlgorithm": {
"anyOf": [
{
"type": "string",
"enum": [
"sha1",
"sha256",
"plain"
]
},
{
"type": "null"
}
]
},
"signaturePrefix": {
"type": "string",
"nullable": true
},
"requestIdentifierPath": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false,
"description": "The security configuration of the webhook, used to tell Port how to verify the hashed signature sent with incoming requests.<br/>For more information and examples, check out the [documentation](https://docs.port.io/context-lake/ingestion/ingest-data-into-port/webhook/ingest-via-webhooks-overview#security-configuration)."
},
"integrationType": {
"type": "string",
"enum": [
"custom",
"template"
]
}
},
"additionalProperties": false,
"required": [
"title",
"enabled"
]
}
}
},
"required": true
}
}Responses
- 401
- 404
- 413
- 422
Default Response
A resource with the provided identifier was not found
Request body is too large (limit is 1MiB)
The json provided does not match the route's schema
Responses (JSON)
{
"responses": {
"401": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"properties": {
"ok": {
"const": false
},
"error": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"ok",
"error"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "A resource with the provided identifier was not found",
"content": {
"application/json": {
"schema": {
"properties": {
"ok": {
"const": false
},
"error": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"ok",
"error",
"message"
],
"additionalProperties": false,
"description": "A resource with the provided identifier was not found"
}
}
}
},
"413": {
"description": "Request body is too large (limit is 1MiB)",
"content": {
"application/json": {
"schema": {
"properties": {
"ok": {
"const": false
},
"error": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"ok",
"error"
],
"additionalProperties": false,
"description": "Request body is too large (limit is 1MiB)"
}
}
}
},
"422": {
"description": "The json provided does not match the route's schema",
"content": {
"application/json": {
"schema": {
"properties": {
"ok": {
"const": false
},
"error": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"ok",
"error",
"message"
],
"additionalProperties": false,
"description": "The json provided does not match the route's schema"
}
}
}
}
}
}