External Integration

External Integrations allow customers to push events directly to RedCarbon via webhook, rather than having RedCarbon poll a vendor API. This is useful for proprietary systems or custom tools that can send HTTP requests but don't have a native RedCarbon integration.

For standard vendor integrations (where RedCarbon polls the data), see Integrations.

Configuration

External integrations are configured per customer:

1. Navigate to Organization Admin > Customers.
2. Click on the customer name to open the details.
3. Open the External Integration tab.
4. Click Generate Key and set an expiration date.
5. Copy the generated API key — it will be shown only once.
6. Share the key and the endpoint URL with the customer so they can configure their system to push events.

Field Parser

Once the integration is created, a code editor allows you to define a parser function that remaps or transforms the incoming payload before RedCarbon processes it. This is necessary when the upstream system sends fields with non-standard names or formats.

When the integration is created, the editor is pre-populated with a minimal template:

const parser: ParserFunc = (raw) => {
    const data = json(raw);

    return {
        classification: {
            type: 'test'
        },
        description: 'this is a test function'
    }
}

This is enough to verify that events are reaching RedCarbon. From here, you can expand the parser to remap your payload's fields into a richer structure. For example:

const parser: ParserFunc = (raw) => {
    const data = json(raw);
    const log = data.event;

    // Remap vendor severity strings to RedCarbon's 0-100 scale
    const severityMap = { low: 20, medium: 45, high: 75, critical: 90 };
    const severity = severityMap[log.severity] ?? 20;

    return {
        description: log.message,
        classification: {
            type: log.event_type ?? 'Firewall',
            subtype: log.attack ?? 'Generic Incident'
        },
        severity,
        networkTraffics: [{
            srcIp: log.src_ip,
            dstIp: log.dst_ip,
            srcPort: parseInt(log.src_port),
            dstPort: parseInt(log.dst_port),
            protocols: log.app ? [log.app] : [],
            tags: []
        }],
        users: log.username
            ? [{ userName: log.username, tags: [] }]
            : [],
        ipArtifacts: [log.src_ip, log.dst_ip]
            .filter(Boolean)
            .map(ip => ({ ip })),
        tags: ['my-custom-source'],
        detectionEngines: ['my-siem']
    };
}

The more fields you map, the more RedCarbon can do with the event: richer enrichment, better correlation across cases, and more accurate detection. To verify the result of your mapping, review the Raw Data section of an ingested case.

Field Mapping

RedCarbon is able to recognise common values (such as IP addresses) even without an explicit mapping. However, a correct field mapping significantly increases the system's ability to understand and correlate the event.

Example
external_ip: 172.217.16.142	✓ RedCarbon can enrich and correlate the IP
eiadsar: 172.217.16.142	✗ Value ingested, but meaning is lost

A well-mapped payload improves detection accuracy, alert enrichment, and analyst readability.

When to use

External integrations are a good fit for:

• Quick tests — validate that a source can reach RedCarbon without setting up a full integration.
• Proprietary systems — internal tools or custom SIEMs that can send webhooks but have no native integration.
• One-off sources — temporary or low-volume sources where a full polling integration is not justified.