Process real-time events with AWS AppSync event handlers

Overview

AWS AppSync Event handlers let you run custom business logic on real-time events.

These JavaScript functions:

This topic covers simple event handlers without data source integration. For information about integrating with data sources like DynamoDB tables and Lambda functions, see:

onPublish handler

Use the onPublish handler to process and filter events before they reach subscribers. This handler runs each time an event is published to a channel.

The handler uses this signature:

function onPublish(context: Context): OutgoingEvent[] | null

type Context = {
  events: IncomingEvent[];  // Array of events to process
  channel: string;          // Channel the events were published to
  identity: Identity;       // Information about the publisher
  info: {
    channel: {
      path: string;        // Full channel path
      segments: string[];  // Path segments
    }
  }
  channelNamespace: {
    name: string
  }
  operation: 'SUBSCRIBE' | 'PUBLISH'
}

The handler receives a context object with:

For more information on the context object reference, see the Context Reference Guide.

Common onPublish tasks

Forward all events

The default API behavior for the onPublish handler forwards all received events. The onPublish function needs a context object as a parameter.

export function onPublish(ctx) {
  return ctx.events
}

Filter specific events

Filter out events and return only those matching specific criteria. In the following example, the handler filters the events and only forwards those that have odds greater than 0.5.

export function onPublish(ctx) {
  return ctx.events.filter((event) => event.payload.odds > 0.5)
}

Transform events

Transform events by mapping them to a new shape. In the following example, the handler below formats each event to include a timestamp and changes the message to upper case format.

import { util } from '@aws-appsync/utils'

export function onPublish(ctx) {
  return ctx.events.map(event => ({
    id: event.id,
    payload: {
      ...event.payload,
      message: event.payload.message.toUpperCase(),
      timestamp: util.time.nowISO8601()
    }
  }))
}

Important rules for onPublish

onSubscribe handler

Use the onSubscribe handler to authorize and process subscription requests before allowing channel subscriptions. The handler in the following example runs when the client subscribes.

The handler uses this signature:

function onSubscribe(context: Context): void

For more information on the context object reference, see the Context Reference Guide.

Examples

export function onSubscribe(ctx) {
  if (ctx.identity.groups.includes('admin')) {
    console.log(`Admin ${ctx.identity.sub} subscribed to ${ctx.channel}`)
  }
}

export function onSubscribe(ctx) {
  const requested = ctx.info.channel.path
  const allowed = `/messages/inbox/${ctx.identity.username}`
  
  if (requested !== allowed) {
    util.unauthorized()
  }
}

Error handling

Use error handling to manage invalid requests and provide meaningful feedback to users. This toipic explains how to implement error handling for both HTTP endpoints and WebSocket connections. To reject requests and return errors to publishers or subscribers, use the utility.error function. When the publishing is done using the HTTP endpoint, it returns an HTTP 403 response.

Examples

The following examples demonstrates how to return an error message.

export function onPublish(ctx) {
  return ctx.events.map(event => {
    if (!event.payload.message) {
      event.error = "Message required"
    }
    return event
  })
}

export function onPublish(ctx) {
  util.error("Operation not allowed")
}