> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goldsky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon EventBridge

> Stream processed data into your AWS account through an Amazon EventBridge partner event source

## Overview

Stream processed pipeline data directly into your AWS account through [Amazon EventBridge](https://aws.amazon.com/eventbridge/). Goldsky is an EventBridge SaaS partner, so events arrive on a *partner event source* in your account: no inbound networking, API gateway, or shared credentials required. From there you route events to Lambda, SQS, SNS, Step Functions, Kinesis Firehose, or any other EventBridge target using standard rules.

Each row emitted by the upstream transform is delivered as one EventBridge event, serialized as a JSON object in the event `detail`.

<Note>
  The Amazon EventBridge sink is only available on Turbo pipelines.
</Note>

<Note>
  The EventBridge integration is in limited availability while AWS validation is in progress. Contact Goldsky to have it enabled for your project.
</Note>

## How it works

EventBridge partner integrations have two halves, and you set up each one once:

1. **Goldsky creates a partner event source in your account.** When you register your AWS account, Goldsky calls `CreatePartnerEventSource`, which makes a new partner event source visible in your AWS console. It starts in a `PENDING` state.
2. **You associate the event source with an event bus.** In your AWS console you associate the Goldsky event source with an event bus. Once associated, the event source becomes `ACTIVE` and Goldsky's events begin flowing onto that bus, where your rules route them to targets.

A single event source can back multiple pipeline sinks. Use the `detail_type` field on each sink to distinguish event types when you write routing rules.

## Prerequisites

* A Goldsky project with Turbo pipelines enabled.
* An AWS account where you want to receive events. You will need its 12-digit account ID and permission to manage EventBridge in that account.
* Events are delivered in `us-east-1` or `us-west-2`. Choose the region closest to the consumers that will process the data.

## Setup

<Steps>
  <Step title="Register your AWS account in Goldsky">
    In the pipeline builder, add a sink and choose **Amazon EventBridge**. Create an event source with:

    * **Name**: a short identifier for this event source (letters, numbers, hyphens, and underscores).
    * **Description**: optional human-readable note.
    * **AWS Account ID**: the 12-digit account that will receive events.
    * **AWS Region**: `us-east-1` or `us-west-2`.

    Goldsky creates the partner event source and shows you its full name, for example:

    ```text theme={"dark"}
    aws.partner/goldsky.com/<project-id>/<name>
    ```

    Copy this name; you will see it in the AWS console and reference it from your pipeline.
  </Step>

  <Step title="Associate the event source with an event bus">
    Sign in to the AWS console for the same account and region, then go to **Amazon EventBridge → Integration → Partner event sources**. Find the Goldsky event source from the previous step and choose **Associate with event bus**.

    AWS creates a new event bus named after the event source. The event source moves from `PENDING` to `ACTIVE`, and the sink can now deliver events. Until you complete this step, events are not delivered.
  </Step>

  <Step title="Create rules to route events">
    On the associated event bus, create one or more rules to route events to your targets. A simple rule matching every Goldsky event looks like this:

    ```json theme={"dark"}
    {
      "source": ["aws.partner/goldsky.com/<project-id>/<name>"]
    }
    ```

    To route a specific event type to a specific target, match on `detail-type`:

    ```json theme={"dark"}
    {
      "source": ["aws.partner/goldsky.com/<project-id>/<name>"],
      "detail-type": ["ERC20Transfer"]
    }
    ```

    Attach a target (Lambda, SQS, SNS, Step Functions, Firehose, and so on) to each rule.
  </Step>

  <Step title="Reference the event source in your pipeline">
    Configure the sink with the event source name and a `detail_type`, then deploy the pipeline. See [Configuration](#configuration) below.
  </Step>
</Steps>

## Configuration

```yaml theme={"dark"}
sinks:
  eventbridge_sink:
    type: eventbridge_partner
    from: my_transform
    event_source_name: aws.partner/goldsky.com/my-project/eth-events
    detail_type: ERC20Transfer
    region: us-east-1
```

The EventBridge sink does not use a Goldsky secret. Goldsky delivers events using its own AWS partner credentials, so there are no access keys to manage.

## Parameters

<ParamField path="type" type="string" required>
  Must be `eventbridge_partner`.
</ParamField>

<ParamField path="from" type="string" required>
  The transform or source to read data from.
</ParamField>

<ParamField path="event_source_name" type="string" required>
  The full name of the partner event source created during setup, for example `aws.partner/goldsky.com/my-project/eth-events`. The event source must be `ACTIVE` (associated with an event bus) before the pipeline can deliver events.
</ParamField>

<ParamField path="detail_type" type="string" required>
  The EventBridge `detail-type` applied to every event from this sink, for example `ERC20Transfer`. Use it in event-bus rules to route different event types to different targets.
</ParamField>

<ParamField path="region" type="string" required>
  The AWS region of the event source. Must match the region you selected when registering the account: `us-east-1` or `us-west-2`.
</ParamField>

<ParamField path="description" type="string">
  Optional human-readable description for the sink.
</ParamField>

## Event source states

The dashboard shows the current state of each event source:

| State     | Meaning                                                                                                   |
| --------- | --------------------------------------------------------------------------------------------------------- |
| `PENDING` | Created in Goldsky but not yet associated with an event bus in your AWS console. No events are delivered. |
| `ACTIVE`  | Associated with an event bus. Events are being delivered.                                                 |
| `DELETED` | The event source no longer exists in AWS.                                                                 |

A pipeline can only be deployed against an `ACTIVE` event source. If a source is still `PENDING`, complete the association step in the AWS console first.

## Event format

Goldsky sends each row using the EventBridge `PutPartnerEvents` API, setting three fields:

* **source**: the event source name (`event_source_name`).
* **detail-type**: the `detail_type` you configured.
* **detail**: the row, serialized as a JSON object.

AWS wraps these in the standard EventBridge envelope before delivering to your bus. A row with columns `id`, `from`, and `value` arrives as:

```json theme={"dark"}
{
  "version": "0",
  "id": "7bf73129-1428-4cd3-a780-95db273d1602",
  "detail-type": "ERC20Transfer",
  "source": "aws.partner/goldsky.com/my-project/eth-events",
  "account": "123456789012",
  "time": "2026-01-01T00:00:00Z",
  "region": "us-east-1",
  "resources": [],
  "detail": {
    "id": "0xabc...",
    "from": "0x123...",
    "value": "1000000000000000000"
  }
}
```

Match on `source` and `detail-type` in your rules; read your data from `detail`.

## Delivery behavior

* **Batching**: Events are sent with `PutPartnerEvents`, which accepts at most 20 entries per request. Larger upstream batches are split into multiple 20-entry requests automatically.
* **Retries**: Entries that fail with a retryable error (for example throttling) are retried with exponential backoff, starting at 100ms and capped at 30s. Entries that fail as sender faults (such as a malformed or unauthorized request) fail immediately without retry.
* **Ordering**: Like all EventBridge delivery, ordering is best-effort. Do not rely on events arriving in the order they were produced.
* **Event size**: EventBridge rejects events larger than 256 KB. Use an upstream SQL transform to drop or truncate large columns if your row payloads approach this limit.

## Example

Stream high-value ERC-20 transfers on Ethereum Mainnet to EventBridge for downstream processing:

```yaml theme={"dark"}
name: erc20-to-eventbridge
resource_size: s

sources:
  transfers:
    type: dataset
    dataset_name: ethereum.erc20_transfers
    version: 1.2.0
    start_at: latest

transforms:
  high_value:
    type: sql
    primary_key: id
    sql: |
      SELECT * FROM transfers
      WHERE CAST(value AS DECIMAL) > 1000000000000000000

sinks:
  eventbridge_output:
    type: eventbridge_partner
    from: high_value
    event_source_name: aws.partner/goldsky.com/my-project/eth-events
    detail_type: HighValueTransfer
    region: us-east-1
```

## Best practices

<AccordionGroup>
  <Accordion title="Associate the event bus before deploying">
    A pipeline can only deploy against an `ACTIVE` event source. Complete the **Associate with event bus** step in the AWS console so the source leaves `PENDING` before you deploy.
  </Accordion>

  <Accordion title="Use detail_type to route events">
    Give each sink a meaningful `detail_type` and match on it in your event-bus rules. This lets one event source feed many targets: for example, route `HighValueTransfer` to an alerting Lambda and everything else to an archival Firehose.
  </Accordion>

  <Accordion title="Filter at the source, not just in rules">
    EventBridge rules filter after delivery, and you pay for every event put on the bus. Use an upstream SQL transform to emit only the rows you need rather than publishing everything and filtering downstream.
  </Accordion>

  <Accordion title="Stay within the 256 KB event size limit">
    EventBridge rejects events larger than 256 KB. Drop or truncate large columns in a SQL transform if your rows are big.
  </Accordion>

  <Accordion title="Delete unused event sources">
    Remove event sources you no longer use from the Goldsky dashboard. Deletion is blocked while any pipeline still references the source, so detach it from your pipelines first.
  </Accordion>
</AccordionGroup>


## Related topics

- [Turbo - Supported sinks](/turbo-pipelines/sinks/overview.md)
- [SQS](/turbo-pipelines/sinks/sqs.md)
- [Prometheus integration](/turbo-pipelines/prometheus-integration.md)
- [Decode contract events](/turbo-pipelines/guides/decoding-contract-events.md)
- [Cross-chain USDC settlement ledger](/solutions/cross-chain-settlement.md)