Custom Webhook - EasyAlert

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 / alertName
message_title / messageTitle
event_name / eventName

Description Fields

description, message, body, text, details, content
alert_message / alertMessage
event_description / eventDescription

Severity Fields

severity, priority, level, criticality
alert_severity / alertSeverity
event_severity / eventSeverity

Status Fields

status, state
alert_status / alertStatus
event_status / eventStatus
current_state / currentState

Host Fields

host, hostname, server, node, instance, machine
host_name / hostName
target, source_host / sourceHost

IP Address Fields

hostIp, host_ip, ip
ip_address / ipAddress
source_ip / sourceIp

Service Fields

service, application, app, component
service_name / serviceName
app_name / appName

Timestamp Fields

timestamp, time, datetime, date
event_time / eventTime
created_at / createdAt
occurred_at / occurredAt
start_time / startTime

Environment Fields

environment, env
environment_name / environmentName

Other Fields

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

Severity Values

These values are automatically mapped:

Input Value	EasyContact Severity
critical, crit, high, disaster, fatal, emergency, P1, sev1, severity1	Critical
error, err, medium, major, P2, sev2, severity2	High
warning, warn, low, minor, average, P3, sev3, severity3	Warning
info, information, informational, notice, not_classified, P4, P5, sev4, sev5	Info
ok, resolved, recovery, clear, normal	OK

Values are case-insensitive.

Status Values

Input Value	EasyContact Status
ok, resolved, recovery, clear, normal, closed, inactive, resolved_with_alert	OK
(any other value, e.g., problem, alert, triggered, firing)	Problem

Any status value not in the OK list is treated as Problem. You don’t need to send a specific “problem” value — it’s the default.

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.

​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

​Timestamp 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

Timestamp 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