EventBridge Integration

Overview

EventBridge integration allows you to publish events when data changes in your schemas, and receive events from external systems to trigger operations in your backend API.

Two-way Integration:

Output (Publishing): Automatically publish events to EventBridge when data is created, updated, or deleted via POST, PUT, PATCH, or DELETE operations.
Input (Consuming): Receive events from EventBridge and process them through your backend API, with normal billing and routing.

📤 EventBridge Output (Publishing Events)

Configuration

EventBridge output is configured at the tenant level in your tenant properties file. You can configure multiple EventBridge rules per tenant, each targeting different schemas or EventBridge buses.

Configuration Format

Add an array of EventBridge configurations to your tenant properties:

[
        {
        "eventbridge_arn": "arn:aws:events:us-east-1:720291373173:event-bus/default",
        "source": "blockforger-output",
        "detail_type": "petstore.POST",
        "operations": ["POST", "PUT", "PATCH", "DELETE"],
        "schema_names": ["petstore", "orders"]
        },
        {
        "eventbridge_arn": "arn:aws:events:us-east-1:720291373173:event-bus/default",
        "source": "myapp.backend-output",
        "operations": ["POST", "DELETE"],
        "schema_names": ["analytics"]
        }
        ]

Configuration Fields

eventbridge_arn (required): ARN of the EventBridge bus to publish events to. Default: "arn:aws:events:us-east-1:720291373173:event-bus/default". For custom buses, use format: "arn:aws:events:region:account-id:event-bus/bus-name". Can be in another AWS account if properly authorized. Note: You publish to buses, not rules. Rules on the bus will match and route events automatically.
source (optional): Source identifier for events. Defaults to "blockforger-output". For output events (published by the system), use "blockforger-output". For input events (from external systems), use "blockforger-input".
detail_type (optional): Detail type for events. Defaults to "{schema_id}.{operation}" (e.g., "petstore.POST").
operations (optional): List of operations to publish events for. Options: "POST", "PUT", "PATCH", "DELETE". If not specified, all write operations are published.
schema_names (optional): Array of schema IDs (without .json extension) to filter which schemas trigger events. If not specified or empty, all schemas match. Earlier array elements are prioritized when multiple rules match.

Multiple Rules: You can configure multiple EventBridge rules in the array. Events are published to all matching rules. Rules are evaluated in order, and earlier rules are prioritized. If a schema matches multiple rules, events are published to all matching EventBridge buses.

Event Format

Events published to EventBridge have the following structure:

{
        "source": "blockforger-output",
        "detail-type": "petstore.POST",
        "detail": {
        "tenant": "mytenant",
        "rootSchema": "petstore",
        "operation": "POST",
        "payload": {
        // The actual data payload from the request
        "id": "123",
        "name": "Fluffy",
        "status": "available"
        }
        }
        }

Example: Single Rule for All Schemas

In your tenant properties file (schemas/{tenant}/tenant.properties), add:

        eventbridge-output=[{"eventbridge_arn":"arn:aws:events:us-east-1:720291373173:event-bus/default","source":"blockforger-output","operations":["POST","PUT","DELETE"]}]
      

Example: Multiple Rules with Schema Filtering

Configure different EventBridge buses for different schemas:

eventbridge-output=[
        {
        "eventbridge_arn": "arn:aws:events:us-east-1:720291373173:event-bus/default",
        "source": "blockforger-output",
        "operations": ["POST", "PUT", "PATCH", "DELETE"],
        "schema_names": ["petstore", "orders"]
        },
        {
        "eventbridge_arn": "arn:aws:events:us-east-1:720291373173:event-bus/default",
        "source": "blockforger-output",
        "operations": ["POST", "DELETE"],
        "schema_names": ["analytics", "events"]
        },
        {
        "eventbridge_arn": "arn:aws:events:us-east-1:720291373173:event-bus/default",
        "source": "blockforger-output",
        "operations": ["DELETE"],
        "schema_names": []
        }
        ]

In this example:

petstore and orders schemas publish to production-bus for all operations
analytics and events schemas publish to analytics-bus for POST and DELETE only
All schemas (empty schema_names) publish DELETE operations to audit-bus

⚠️ Cross-Account Events: To publish events to an EventBridge bus in another AWS account, you need to configure a resource-based policy on the target EventBridge bus that allows your account to publish events. See AWS EventBridge documentation for details.

📥 EventBridge Input (Consuming Events)

How It Works

When an event is sent to EventBridge with the correct format, it automatically triggers your backend API lambda function. The event is processed as if it came through the API Gateway, with normal routing, validation, and billing.

⚠️ Tenant Configuration Required: EventBridge input must be enabled for your tenant. Add eventbridge-input=true to your tenant properties file (schemas/{tenant}/tenant.properties). Without this flag, EventBridge input events will be rejected with a 403 Forbidden response.

Event Format for Input

Events must have the following structure to be processed. The EventBridge rule requires all fields in detail to exist:

{
        "source": "blockforger-input",
        "detail-type": "petstore.POST",
        "detail": {
        "tenant": "mytenant",
        "rootSchema": "petstore",
        "api_key": "your-api-key-here",
        "operation": "POST",
        "payload": {
        "id": "123",
        "name": "Fluffy",
        "status": "available"
        }
        }
        }

⚠️ Required Fields: All of these fields in detail are required by the EventBridge rule:

tenant - Your tenant ID
rootSchema - Schema ID (without .json extension)
api_key - Valid API key for the tenant with backend_calls permission (required for billing)
payload - The data payload for the operation

The operation field is optional for POST (defaults to POST) but should be included for clarity.

For PUT, PATCH, and DELETE operations, include the item ID in the payload:

{
        "source": "blockforger-input",
        "detail-type": "petstore.PUT",
        "detail": {
        "tenant": "mytenant",
        "rootSchema": "petstore",
        "operation": "PUT",
        "api_key": "your-api-key-here",
        "payload": {
        "id": "123", // Required: the key field value
        "name": "Fluffy Updated",
        "status": "sold"
        }
        }
        }

⚠️ API Key Required: The api_key field is required in the event detail. The API key must:

Belong to the tenant specified in the event
Have the backend_calls permission enabled
Be valid and active

This is required for billing purposes - the tenant associated with the API key will be billed for the operation (10 tokens per request).

Supported Operations

POST: Create a new item
PUT: Replace an existing item (requires item ID in payload)
PATCH: Partially update an existing item (requires item ID in payload)
DELETE: Delete an item (requires item ID in payload)

Billing

Events processed through EventBridge input are billed normally (10 tokens per request), just like API Gateway requests. The tenant specified in the event is billed for the operation.

EventBridge Rule Configuration

The system automatically creates an EventBridge rule that routes events with:

Source: "blockforger-input" (for input events from external systems)
Source: "blockforger-output" (for output events published by the system)
Detail-type: Pattern matching "*.POST", "*.PUT", "*.PATCH", "*.DELETE"
Detail containing: tenant, rootSchema, api_key, and payload fields

This rule is configured in the CloudFormation template and routes matching events to your backend API lambda.

API Key Validation: Before processing an EventBridge input event, the system validates that:

The api_key field is present in the event detail
The API key belongs to the tenant specified in the event
The API key has the backend_calls permission

If validation fails, the event is rejected with a 401 Unauthorized response.

🧪 Testing

Test Lambda Function

A no-op test lambda function is automatically created for integration testing. This lambda:

Receives EventBridge events
Logs all event details to CloudWatch
Terminates without performing any operations

To use the test lambda, configure your EventBridge output to point to the test EventBridge bus or rule. Check CloudWatch logs for the eventbridge-test-{environment} lambda function to see received events.

Testing Event Publishing

Configure EventBridge output in your tenant properties or schema meta
Perform a POST, PUT, PATCH, or DELETE operation via the API
Check CloudWatch logs for the test lambda to verify the event was published
Check the EventBridge console to see events in your bus

Testing Event Consumption

Use the AWS CLI to send an event to EventBridge. The EventBridge rule matches events with:

Source: "blockforger-input"
DetailType: Pattern matching "*.POST", "*.PUT", "*.PATCH", "*.DELETE" (e.g., "petstore.POST")
Detail fields: tenant, rootSchema, api_key, payload (all required)

Using a JSON file (recommended):

aws events put-events --entries file://event.json

Create event.json with the following content (replace YOUR_TENANT, YOUR_SCHEMA, and YOUR_API_KEY):

[
        {
        "Source": "blockforger-input",
        "DetailType": "YOUR_SCHEMA.POST",
        "EventBusName": "default",
        "Detail": {
        "tenant": "YOUR_TENANT",
        "rootSchema": "YOUR_SCHEMA",
        "operation": "POST",
        "api_key": "YOUR_API_KEY",
        "payload": {
        "numeric": 21,
        "string": "ergyigyuhwer"
        }
        }
        }
        ]

Or using inline JSON (requires stringified Detail):

aws events put-events --entries
        '[{"Source":"blockforger-input","DetailType":"YOUR_SCHEMA.POST","EventBusName":"default","Detail":"{\"tenant\":\"YOUR_TENANT\",\"rootSchema\":\"YOUR_SCHEMA\",\"operation\":\"POST\",\"api_key\":\"YOUR_API_KEY\",\"payload\":{\"numeric\":21,\"string\":\"ergyigyuhwer\"}}"}]'
      

Example with actual values (tenant: 'evented', schema: 'evented'):

aws events put-events --entries file://event.json

Where event.json contains:

[
        {
        "Source": "blockforger-input",
        "DetailType": "evented.POST",
        "EventBusName": "default",
        "Detail": {
        "tenant": "evented",
        "rootSchema": "evented",
        "operation": "POST",
        "api_key": "YOUR-API-KEY-HERE",
        "payload": {
        "numeric": 21,
        "string": "ergyigyuhwer"
        }
        }
        }
        ]

⚠️ Important:

Credentials: Replace YOUR-API-KEY-HERE with a valid API key for the tenant. The API key must belong to the specified tenant and have backend_calls permission.
Detail field: When using a JSON file, Detail can be a JSON object. When using inline JSON, Detail must be a JSON string (escaped). All fields in detail are required: tenant, rootSchema, api_key, and payload.
Event Bus: Use "EventBusName": "default" for the default EventBridge bus, or omit it. The EventBridge rule listens on the default bus.
Operation: The operation field in detail is optional for POST (defaults to POST), but required for PUT, PATCH, and DELETE.

After sending the event:

The event will automatically route to your backend API lambda
Check CloudWatch logs for the backend API lambda to see processing
Verify the operation was performed (check DynamoDB, CSV, or S3 depending on your backend configuration)

📚 Additional Resources

← Back to Home