Custom Webhook

Overview

The Custom integration allows you to connect any monitoring tool, script, or application that can send HTTP POST requests. EasyContact automatically extracts common fields and captures additional data as tags.

Use Custom integration when your monitoring tool isn’t in our supported list, or when you want to send alerts from custom applications.

Setup Instructions

Create Integration in EasyContact

Go to Configuration → Integrations
Click Add Integration
Select Custom as the type
Enter a name (e.g., “Internal Monitoring”)
Save and copy the webhook URL

Configure Your Source

Set up your monitoring tool or script to POST JSON to the webhook URL

Send a Test Event

Send a test payload and verify it appears in EasyContact

Configure Mappings

Adjust severity mapping and enrichment based on your payload structure

Webhook URL

Your webhook URL:

https://api.easycontact.ai/api/v1/webhooks/ingest/{token}

Request Format

Setting	Value
Method	POST
Content-Type	application/json
Authentication	None (token in URL)

Recommended Payload Format

Send events in this structure for best results:

{
  "eventId": "unique-event-id-123",
  "title": "Alert title",
  "description": "Detailed description of the alert",
  "severity": "critical",
  "status": "problem",
  "host": "server-name",
  "hostIp": "192.168.1.100",
  "service": "service-name",
  "environment": "production",
  "timestamp": "2024-01-15T10:30:00Z",
  "url": "https://your-monitoring-tool/alert/123",
  "tags": {
    "team": "platform",
    "region": "eu-west-1"
  }
}

Field Recognition

EasyContact automatically recognizes these common field names:

Title Fields

title
name
subject
summary
alert_name
message_title

Description Fields

description
message
body
text
details

Severity Fields

severity
priority
level
criticality

Status Fields

status
state
alert_status
current_state

Host Fields

host
hostname
server
node
instance
machine

IP Address Fields

hostIp
host_ip
ip
ip_address
source_ip

Service Fields

service
application
app
component

Environment Fields

environment
env

Other Fields

region, datacenter, dc, location
team, owner
customer, client, tenant

Severity Values

These values are automatically mapped:

Input Value	EasyContact Severity
critical, disaster, fatal, emergency, P1	Critical
error, high, major, P2	High
warning, warn, medium, minor, average, P3	Warning
info, information, low, notice, P4, P5	Info
ok, resolved, recovery, clear, success	OK

Values are case-insensitive.

Status Values

Input Value	EasyContact Status
problem, alert, alerting, triggered, firing, open, active	Problem
ok, resolved, recovery, clear, closed, inactive	OK

Tags Handling

All unrecognized fields are captured as tags:

{
  "title": "Alert",
  "severity": "warning",
  "custom_field_1": "value1",
  "custom_field_2": "value2"
}

Results in tags:

custom_field_1: value1
custom_field_2: value2

Nested Tags

You can also send structured tags:

{
  "tags": {
    "environment": "production",
    "team": "platform",
    "service": "api"
  }
}

Example Payloads

Minimal Payload

{
  "title": "High CPU Usage",
  "severity": "critical",
  "host": "web-01"
}

Full Payload

{
  "eventId": "evt-12345",
  "title": "Database connection pool exhausted",
  "description": "All database connections are in use. New requests are being queued.",
  "severity": "critical",
  "status": "problem",
  "host": "db-server-01",
  "hostIp": "10.0.1.50",
  "service": "postgresql",
  "environment": "production",
  "region": "us-east-1",
  "timestamp": "2024-01-15T10:30:00Z",
  "url": "https://internal-monitoring.example.com/alerts/12345",
  "tags": {
    "team": "database",
    "tier": "critical",
    "customer": "acme-corp"
  },
  "metrics": {
    "active_connections": 100,
    "max_connections": 100,
    "queue_length": 25
  }
}

Recovery Payload

{
  "eventId": "evt-12345",
  "title": "Database connection pool exhausted",
  "status": "resolved",
  "timestamp": "2024-01-15T10:45:00Z"
}

Custom Severity Mapping

If your tool uses custom severity values:

{
  "severityMapping": {
    "sourceField": "priority",
    "mappings": {
      "urgent": "critical",
      "high": "high",
      "medium": "warning",
      "low": "info"
    },
    "default": "warning"
  }
}

Enrichment Examples

Add context to all custom alerts:

{
  "enrichment": {
    "tags.source": "custom-monitoring",
    "tags.datacenter": "dc1",
    "owner": "ops-team"
  }
}

cURL Examples

Sending an Alert

curl -X POST "YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test Alert",
    "severity": "warning",
    "host": "test-server",
    "description": "This is a test alert"
  }'

Sending a Recovery

curl -X POST "YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "same-event-id",
    "status": "resolved"
  }'

Integration Examples

From a Shell Script

#!/bin/bash

WEBHOOK_URL="YOUR_WEBHOOK_URL"

# Check disk usage
DISK_USAGE=$(df -h / | awk 'NR==2 {print $5}' | tr -d '%')

if [ "$DISK_USAGE" -gt 90 ]; then
  curl -X POST "$WEBHOOK_URL" \
    -H "Content-Type: application/json" \
    -d "{
      \"title\": \"High Disk Usage\",
      \"severity\": \"critical\",
      \"host\": \"$(hostname)\",
      \"description\": \"Disk usage is at ${DISK_USAGE}%\"
    }"
fi

From Python

import requests
import json

webhook_url = "YOUR_WEBHOOK_URL"

payload = {
    "title": "Application Error",
    "severity": "high",
    "host": "app-server-01",
    "service": "payment-service",
    "description": "Payment processing failed",
    "tags": {
        "error_code": "PAY-001",
        "transaction_id": "txn-12345"
    }
}

response = requests.post(
    webhook_url,
    headers={"Content-Type": "application/json"},
    data=json.dumps(payload)
)

print(f"Status: {response.status_code}")

From Node.js

const axios = require('axios');

const webhookUrl = 'YOUR_WEBHOOK_URL';

const payload = {
  title: 'Service Degradation',
  severity: 'warning',
  host: 'api-gateway',
  service: 'user-service',
  description: 'Response times increased by 50%',
  tags: {
    p99_latency: '2500ms',
    error_rate: '2.5%'
  }
};

axios.post(webhookUrl, payload)
  .then(response => console.log('Alert sent:', response.status))
  .catch(error => console.error('Error:', error.message));

Troubleshooting

Webhook returns error

Verify Content-Type is application/json
Ensure payload is valid JSON
Check webhook URL is correct
Look at response body for error details

Fields not being extracted

Use recognized field names from the list above
Check field name spelling and casing
View webhook samples to see parsed result

Wrong severity assigned

Check severity value spelling
Configure custom severity mapping
Set appropriate default severity

Recovery not resolving incident

Include same eventId in recovery
Set status to “resolved” or “ok”
Verify both payloads reach EasyContact

Best Practices

Use Consistent Event IDs

Include a unique eventId that stays consistent between alert and recovery. This enables automatic incident resolution.

Include Relevant Context

Add host, service, and environment fields to help responders quickly understand the alert.

Use Tags for Routing

Add tags that can be used in escalation routing rules (team, environment, customer).

Test Thoroughly

Send test alerts and recoveries before relying on the integration in production.

Include URLs

Add links to your monitoring tool or relevant dashboards in the url field.

Getting started

Management

Configuration

Access Management

Overview

Setup Instructions

Webhook URL

Request Format

Recommended Payload Format

Field Recognition

Title Fields

Description Fields

Severity Fields

Status Fields

Host Fields

IP Address Fields

Service Fields

Environment Fields

Other Fields

Severity Values

Status Values

Tags Handling

Nested Tags

Example Payloads

Minimal Payload

Full Payload

Recovery Payload

Custom Severity Mapping

Enrichment Examples

cURL Examples

Sending an Alert

Sending a Recovery

Integration Examples

From a Shell Script

From Python

From Node.js

Troubleshooting

Best Practices

Getting started

Management

Configuration

Access Management

​Overview

​Setup Instructions

​Webhook URL

​Request Format

​Recommended Payload Format

​Field Recognition

​Title Fields

​Description Fields

​Severity Fields

​Status Fields

​Host Fields

​IP Address Fields

​Service Fields

​Environment Fields

​Other Fields

​Severity Values

​Status Values

​Tags Handling

​Nested Tags

​Example Payloads

​Minimal Payload

​Full Payload

​Recovery Payload

​Custom Severity Mapping

​Enrichment Examples

​cURL Examples

​Sending an Alert

​Sending a Recovery

​Integration Examples

​From a Shell Script

​From Python

​From Node.js

​Troubleshooting

​Best Practices

Overview

Setup Instructions

Webhook URL

Request Format

Recommended Payload Format

Field Recognition

Title Fields

Description Fields

Severity Fields

Status Fields

Host Fields

IP Address Fields

Service Fields

Environment Fields

Other Fields

Severity Values

Status Values

Tags Handling

Nested Tags

Example Payloads

Minimal Payload

Full Payload

Recovery Payload

Custom Severity Mapping

Enrichment Examples

cURL Examples

Sending an Alert

Sending a Recovery

Integration Examples

From a Shell Script

From Python

From Node.js

Troubleshooting

Best Practices