Temporal Ts Interceptors

How to Use

Environment Context Gathering

Before implementing interceptors, confirm the following with the user:

1. Where is Temporal running? (local dev server via temporal server start-dev, Docker Compose, Kubernetes, Temporal Cloud)
2. If not local, what is the full Temporal gRPC endpoint URL? (e.g. my-namespace.abc123.tmprl.cloud:7233)
3. Is ingress configured for the Temporal HTTP API? (needed if the Web UI or temporal CLI must reach the cluster from outside)

These answers determine connection options and whether mTLS certificates are required when constructing the Client.

Quick Reference

Implementation Patterns

Pattern 1 -- Workflow Outbound Interceptor (Activity Logging)

Intercept outbound calls from a workflow to log every activity that is scheduled.

// src/workflows/interceptors.ts
import {
  ActivityInput,
  Next,
  WorkflowOutboundCallsInterceptor,
  workflowInfo,
} from '@temporalio/workflow';

export class ActivityLogInterceptor
  implements WorkflowOutboundCallsInterceptor
{
  constructor(public readonly workflowType: string) {}

  async scheduleActivity(
    input: ActivityInput,
    next: Next<WorkflowOutboundCallsInterceptor, 'scheduleActivity'>,
  ): Promise<unknown> {
    console.log('Starting activity', { activityType: input.activityType });
    try {
      return await next(input);
    } finally {
      console.log('Completed activity', {
        workflow: this.workflowType,
        activityType: input.activityType,
      });
    }
  }
}

// Export the interceptors factory function (REQUIRED for workflow interceptors)
export const interceptors = () => ({
  outbound: [new ActivityLogInterceptor(workflowInfo().workflowType)],
  inbound: [],
});

Pattern 2 -- Workflow Inbound Interceptor (Authorization)

Inspect headers on inbound workflow execution for auth tokens.

// src/workflows/auth-interceptor.ts
import {
  defaultDataConverter,
  Next,
  WorkflowInboundCallsInterceptor,
  WorkflowInput,
} from '@temporalio/workflow';

export class WorkflowAuthInterceptor
  implements WorkflowInboundCallsInterceptor
{
  async execute(
    input: WorkflowInput,
    next: Next<WorkflowInboundCallsInterceptor, 'execute'>,
  ): Promise<unknown> {
    const authHeader = input.headers.auth;
    if (!authHeader) {
      throw new Error('Missing auth header');
    }
    const { user, role } = await defaultDataConverter.fromPayload(authHeader);
    if (role !== 'admin') {
      throw new Error('Unauthorized: admin role required');
    }
    return await next(input);
  }
}

export const interceptors = () => ({
  inbound: [new WorkflowAuthInterceptor()],
  outbound: [],
});

Pattern 3 -- Activity Inbound Interceptor

Intercept activity execution on the Worker side (runs in normal Node.js, not the workflow isolate).

// src/activities/interceptors.ts
import {
  ActivityInboundCallsInterceptor,
  ActivityExecuteInput,
  Next,
} from '@temporalio/worker';
import { Context } from '@temporalio/activity';

export class ActivityMetricsInterceptor
  implements ActivityInboundCallsInterceptor
{
  async execute(
    input: ActivityExecuteInput,
    next: Next<ActivityInboundCallsInterceptor, 'execute'>,
  ): Promise<unknown> {
    const startTime = Date.now();
    try {
      return await next(input);
    } finally {
      const duration = Date.now() - startTime;
      console.log(`Activity ${Context.current().info.activityType} took ${duration}ms`);
    }
  }
}

Pattern 4 -- Client Interceptor

Intercept client-side calls such as starting or signaling a workflow.

// src/client/interceptors.ts
import {
  WorkflowClientInterceptor,
  WorkflowStartInput,
  Next,
} from '@temporalio/client';

export class ClientLoggingInterceptor implements WorkflowClientInterceptor {
  async start(
    input: WorkflowStartInput,
    next: Next<WorkflowClientInterceptor, 'start'>,
  ): Promise<unknown> {
    console.log('Starting workflow', {
      workflowId: input.workflowId,
      workflowType: input.workflowType,
    });
    return await next(input);
  }
}

Registration

Workflow Interceptors (isolate constraint)

Workflow interceptors run inside the deterministic V8 isolate. You must:

1. Export an interceptors factory function from a file in your workflows directory.
2. Point the Worker to that file via workflowModules.

// src/worker.ts
import { Worker } from '@temporalio/worker';

const worker = await Worker.create({
  workflowsPath: require.resolve('./workflows'),
  interceptors: {
    workflowModules: [require.resolve('./workflows/interceptors')],
  },
  taskQueue: 'my-task-queue',
});

Activity Interceptors

Pass factory functions directly on Worker creation:

import { Worker } from '@temporalio/worker';
import { ActivityMetricsInterceptor } from './activities/interceptors';

const worker = await Worker.create({
  workflowsPath: require.resolve('./workflows'),
  activities,
  interceptors: {
    activity: [() => new ActivityMetricsInterceptor()],
  },
  taskQueue: 'my-task-queue',
});

Client Interceptors

Pass interceptors when constructing the Client:

import { Client } from '@temporalio/client';
import { ClientLoggingInterceptor } from './client/interceptors';

const client = new Client({
  interceptors: {
    workflow: [new ClientLoggingInterceptor()],
  },
});

OpenTelemetry Tracing (Built-in Package)

The SDK ships @temporalio/interceptors-opentelemetry for automatic span propagation.

npm install @temporalio/interceptors-opentelemetry @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-grpc

See the full working sample: temporalio/samples-typescript/interceptors-opentelemetry.

Common Mistakes

Debugging Tips

1. Interceptor not firing? Verify the file is listed in workflowModules (for workflow interceptors) or the factory is in the correct interceptors array on Worker/Client creation.
2. Non-determinism errors? You likely imported a disallowed module in a workflow interceptor file. Only @temporalio/workflow imports are safe there.
3. Chain order matters. Interceptors execute in array order. The first interceptor in the array is the outermost wrapper.
4. Use workflowInfo() inside workflow interceptor constructors to access the current workflow type, run ID, and other metadata for conditional logic.
5. Test interceptors in isolation by calling them directly with mock input and a mock next function before integrating into a Worker.

Further Resources

If this skill does not answer your question, use Context7 to search /temporalio/sdk-typescript or /temporalio/samples-typescript for more details. Useful queries:

• "How to register OpenTelemetry interceptors with the Worker"
• "WorkflowInboundCallsInterceptor interface methods"
• "Activity interceptor factory function signature"
• "Client interceptor for signal and query"