Webhook Connection

General Information

Connection Type

webhook

UI Documentation

📖 For detailed information: [UI Documentation Link - Link will be added here]

Description

Webhook connection for sending HTTP/HTTPS requests to external webhook endpoints. Supports all HTTP methods (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS) with custom headers and connection pooling. Used by policies and connectors to send notifications or data to external systems via HTTP webhooks.

Endpoints

List Connections

GET /apiops/projects/{projectName}/connections/?type=webhook

Get Connection

GET /apiops/projects/{projectName}/connections/{connectionName}/

Create Connection

POST /apiops/projects/{projectName}/connections/{connectionName}/

Update Connection

PUT /apiops/projects/{projectName}/connections/{connectionName}/

Delete Connection

DELETE /apiops/projects/{projectName}/connections/{connectionName}/

List Connections

Endpoint

GET /apiops/projects/{projectName}/connections/?type=webhook

Request

Headers

Header Value
Authorization Bearer {token}

Path Parameters

Parameter Type Required Description
projectName string Yes Project name

Note: The type query parameter is required to filter connections by type.

cURL Example

curl -X GET \
  "https://demo.apinizer.com/apiops/projects/MyProject/connections/" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Connection

Endpoint

GET /apiops/projects/{projectName}/connections/{connectionName}/

Request

Headers

Header Value
Authorization Bearer {token}

Path Parameters

Parameter Type Required Description
projectName string Yes Project name
connectionName string Yes Connection name

Response

Success Response (200 OK)

{
  "success": true,
  "resultList": [
    {
      "type": "webhook",
      "name": "my-webhook-connection",
      "description": "Webhook connection for notifications",
      "deployToWorker": true,
      "enabled": true,
      "httpMethod": "POST",
      "fullUrl": "https://webhook.example.com/api/notify",
      "headerList": [
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Authorization",
          "value": "Bearer token123"
        }
      ],
      "timeout": 5,
      "connectionPoolMaxConnectionPerHost": 24,
      "connectionPoolMaxConnectionTotal": 48
    }
  ],
  "resultCount": 1
}

cURL Example

curl -X GET \
  "https://demo.apinizer.com/apiops/projects/MyProject/connections/my-webhook-connection/" \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Connection

Endpoint

POST /apiops/projects/{projectName}/connections/{connectionName}/

Request

Headers

Header Value
Authorization Bearer {token}
Content-Type application/json

Path Parameters

Parameter Type Required Description
projectName string Yes Project name
connectionName string Yes Connection name

Request Body

Full JSON Body Example - Basic POST Webhook
{
  "type": "webhook",
  "name": "my-webhook-connection",
  "description": "Webhook connection for notifications",
  "deployToWorker": true,
  "enabled": true,
  "httpMethod": "POST",
  "fullUrl": "https://webhook.example.com/api/notify",
  "headerList": [
    {
      "name": "Content-Type",
      "value": "application/json"
    }
  ],
  "timeout": 5,
  "connectionPoolMaxConnectionPerHost": 24,
  "connectionPoolMaxConnectionTotal": 48
}
Full JSON Body Example - GET Webhook with Authentication
{
  "type": "webhook",
  "name": "my-get-webhook",
  "description": "GET webhook with authentication",
  "deployToWorker": true,
  "enabled": true,
  "httpMethod": "GET",
  "fullUrl": "https://api.example.com/webhook?key=value",
  "headerList": [
    {
      "name": "Authorization",
      "value": "Bearer token123"
    },
    {
      "name": "X-API-Key",
      "value": "api-key-12345"
    }
  ],
  "timeout": 10,
  "connectionPoolMaxConnectionPerHost": 50,
  "connectionPoolMaxConnectionTotal": 100
}
Full JSON Body Example - PUT Webhook with Custom Headers
{
  "type": "webhook",
  "name": "my-put-webhook",
  "description": "PUT webhook with custom headers",
  "deployToWorker": true,
  "enabled": true,
  "httpMethod": "PUT",
  "fullUrl": "https://api.example.com/webhook/update",
  "headerList": [
    {
      "name": "Content-Type",
      "value": "application/json"
    },
    {
      "name": "Authorization",
      "value": "Bearer token123"
    },
    {
      "name": "X-Custom-Header",
      "value": "custom-value"
    }
  ],
  "timeout": 30,
  "connectionPoolMaxConnectionPerHost": 24,
  "connectionPoolMaxConnectionTotal": 48
}
Full JSON Body Example - HTTPS Webhook
{
  "type": "webhook",
  "name": "my-https-webhook",
  "description": "Secure HTTPS webhook",
  "deployToWorker": true,
  "enabled": true,
  "httpMethod": "POST",
  "fullUrl": "https://secure.example.com/webhook",
  "headerList": [
    {
      "name": "Content-Type",
      "value": "application/json"
    },
    {
      "name": "Authorization",
      "value": "Bearer secure-token"
    }
  ],
  "timeout": 15,
  "connectionPoolMaxConnectionPerHost": 24,
  "connectionPoolMaxConnectionTotal": 48
}
Request Body Fields
Common Fields
Field Type Required Default Description
type string Yes - Connection type discriminator field. Identifies the connection type in API requests/responses.
name string Yes - Connection name (must match path parameter)
description string No - Connection description
deployToWorker boolean No true Whether to deploy to worker
enabled boolean No true Whether connection is enabled
Webhook-Specific Fields
Field Type Required Default Description
httpMethod string No GET HTTP method. See EnumHttpRequestMethod
fullUrl string Yes - Full webhook URL (including protocol, host, path, and optional query parameters)
headerList array No [] List of HTTP headers to include in requests
timeout integer No 2 Connection timeout in seconds
connectionPoolMaxConnectionPerHost integer No 24 Maximum number of connections per host in connection pool
connectionPoolMaxConnectionTotal integer No 48 Maximum total number of connections in connection pool

Header Object (headerList item)

Field Type Required Description
name string Yes Header name (e.g., “Content-Type”, “Authorization”)
value string Yes Header value

EnumHttpRequestMethod (httpMethod)

  • GET - GET request (default)
  • POST - POST request
  • PUT - PUT request
  • DELETE - DELETE request
  • PATCH - PATCH request
  • HEAD - HEAD request
  • OPTIONS - OPTIONS request

Notes

  • fullUrl is required and must be a valid URL (http:// or https://).
  • httpMethod defaults to GET.
  • timeout is specified in seconds (default: 2 seconds).
  • headerList is an array of header objects with name and value fields.
  • connectionPoolMaxConnectionPerHost limits connections per host (default: 24).
  • connectionPoolMaxConnectionTotal limits total connections (default: 48).
  • HTTPS URLs are supported with SSL/TLS (certificate validation is disabled by default).
  • Query parameters can be included in fullUrl (will be properly encoded).

Response

Success Response (200 OK)

{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": [
      {
        "environmentName": "production",
        "success": true,
        "message": "Deployment successful"
      }
    ]
  }
}

cURL Example

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/connections/my-webhook-connection/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "webhook",
    "name": "my-webhook-connection",
    "description": "Webhook connection for notifications",
    "deployToWorker": true,
    "enabled": true,
    "httpMethod": "POST",
    "fullUrl": "https://webhook.example.com/api/notify",
    "headerList": [
      {
        "name": "Content-Type",
        "value": "application/json"
      }
    ],
    "timeout": 5
  }'

Update Connection

Endpoint

PUT /apiops/projects/{projectName}/connections/{connectionName}/

Request

Headers

Header Value
Authorization Bearer {token}
Content-Type application/json

Path Parameters

Parameter Type Required Description
projectName string Yes Project name
connectionName string Yes Connection name (must match name in body)

Request Body

Full JSON Body Example
{
  "type": "webhook",
  "name": "my-webhook-connection",
  "description": "Updated Webhook connection for notifications",
  "deployToWorker": true,
  "enabled": true,
  "httpMethod": "POST",
  "fullUrl": "https://webhook-new.example.com/api/v2/notify",
  "headerList": [
    {
      "name": "Content-Type",
      "value": "application/json"
    },
    {
      "name": "Authorization",
      "value": "Bearer your-token-here"
    },
    {
      "name": "X-API-Key",
      "value": "your-api-key"
    }
  ],
  "timeout": 10,
  "connectionPoolMaxConnectionPerHost": 50,
  "connectionPoolMaxConnectionTotal": 100
}

Note: Request body structure is the same as Create Connection. All fields should be provided for update.

Response

Success Response (200 OK)

{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": [...]
  }
}

Delete Connection

Endpoint

DELETE /apiops/projects/{projectName}/connections/{connectionName}/

Request

Headers

Header Value
Authorization Bearer {token}

Path Parameters

Parameter Type Required Description
projectName string Yes Project name
connectionName string Yes Connection name

Response

Success Response (200 OK)

{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": [...]
  }
}

Notes and Warnings

  • HTTP Methods:
    • All standard HTTP methods are supported: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
    • Default method is GET
    • POST is commonly used for webhooks
  • URL Format:
    • fullUrl must be a complete URL including protocol (http:// or https://)
    • Query parameters can be included in the URL (will be properly encoded)
    • Example: https://webhook.example.com/api/notify?param=value
  • Headers:
    • headerList is an array of header objects
    • Each header object has name and value fields
    • Common headers: Content-Type, Authorization, X-API-Key, etc.
    • Headers are sent with every request
  • Timeout:
    • timeout is specified in seconds (not milliseconds)
    • Default: 2 seconds
    • Timeout applies to connect, socket, and connection request timeouts
    • Increase timeout for slow networks or long-running operations
  • Connection Pooling:
    • Connection pooling improves performance by reusing connections
    • connectionPoolMaxConnectionPerHost - Maximum connections per host (default: 24)
    • connectionPoolMaxConnectionTotal - Maximum total connections (default: 48)
    • Increase pool sizes for high-throughput scenarios
    • Pool size should be balanced with server capacity
  • SSL/TLS:
    • HTTPS URLs are supported
    • SSL certificate validation is disabled by default (trusts all certificates)
    • Supported protocols: TLSv1.3, TLSv1.2, TLSv1.1, TLSv1, SSLv3, SSLv2Hello
  • Query Parameters:
    • Query parameters can be included in fullUrl
    • Parameters are automatically encoded
    • Example: https://api.example.com/webhook?key=value&param=data
  • Performance:
    • Connection pooling reduces overhead for multiple requests
    • Timeout settings affect request behavior
    • Pool sizes should match expected load
  • Security:
    • Use HTTPS for production webhooks
    • Store sensitive tokens/keys securely
    • Consider using environment variables or secrets management
  • Deployment: Connection changes require deployment to take effect. Set deployToWorker: true or deploy manually.