Application Event Lab

@Controller('webhooks/twilio')
export class WebhookController {
  constructor(private readonly events: ApplicationEvents) {}

  @Post('status')
  @UseGuards(TwilioSignatureGuard)
  @HttpCode(202)
  async receive(@Body() form: TwilioStatusCallback) {
    // Adapter validates schema, maps provider IDs to an application,
    // and derives a stable identity for this callback, not just CallSid.
    const event = await this.events.normalizeTwilio(form);
    await this.events.record(event); // inbox + pending job committed
    return { accepted: true }; // acknowledgement, not completion
  }
}

@Injectable()
export class TwilioSignatureGuard implements CanActivate {
  constructor(private readonly config: WebhookConfig) {}
  canActivate(context: ExecutionContext): boolean {
    const req = context.switchToHttp().getRequest();
    // This endpoint accepts form-encoded callbacks only.
    // Config contains the exact externally configured callback URL.
    const valid = twilio.validateRequest(
      this.config.authToken,
      req.get('X-Twilio-Signature') ?? '',
      this.config.exactPublicCallbackUrl,
      req.body, // original form parameters, before DTO transformation
    );
    if (!valid) throw new ForbiddenException();
    return true;
  }
}

Use the official SDK. Preserve the exact public URL and all original parameters; do not reconstruct it from untrusted forwarded headers. For JSON callbacks, preserve the raw body and use the SDK’s JSON-specific validation method. Secrets belong in server configuration only.

@Injectable()
export class ApplicationEvents {
  constructor(private readonly db: Database) {}
  async record(event: ApplicationEvent) {
    return this.db.transaction(async tx => {
      // INSERT ... ON CONFLICT (provider, event_id) DO NOTHING
      if (!await tx.inbox.insertIfAbsent(event)) return;
      await tx.jobs.insert(event); // same durable transaction
    });
  }
  async process(job: ClaimedJob) {
    return this.db.transaction(async tx => {
      const locked = await tx.jobs.lock(job.id);
      if (locked.done) return;
      const app = await tx.applications.lock(job.event.applicationId);
      if (job.event.sequence <= app.sequence) {
        await tx.jobs.finish(job.id, 'Deferred: Older Event');
        return;
      }
      const next = applyValidatedEvent(app, job.event);
      await tx.applications.save(next); // revision + 1
      await tx.outbox.insert(outboxRecord(job.event, next));
      await tx.jobs.finish(job.id, 'Processed');
    }); // rollback on failure; lease/backoff makes job retryable
  }
}

@Resolver(() => ApplicationView)
@UseGuards(SessionGuard)
export class ApplicationResolver {
  constructor(private readonly apps: Applications) {}
  @Query(() => ApplicationView)
  application(@Args('id') id: string, @CurrentUser() user: User) {
    return this.apps.findAuthorized(id, user.id);
  }
  @Mutation(() => ApplicationView)
  requestReview(@Args('id') id: string, @CurrentUser() user: User) {
    // Check ownership and allowed transition; commit with outbox.
    return this.apps.requestReviewAuthorized(id, user.id);
  }
}

@WebSocketGateway({ namespace: '/applications' })
export class ApplicationGateway {
  @WebSocketServer() server: Server;
  constructor(private readonly access: ApplicationAccess) {}

  @UseGuards(SocketSessionGuard)
  @SubscribeMessage('application.watch')
  async watch(@ConnectedSocket() client: Socket,
              @MessageBody() input: WatchApplicationDto) {
    await this.access.assertOwner(client.data.user.id, input.id);
    await client.join(`application:${input.id}`);
    return { joined: input.id }; // client then refetches via GraphQL
  }
  publish(event: ApplicationUpdated) {
    this.server.to(`application:${event.applicationId}`)
      .emit('application.updated', event);
  }
} // Configure a Redis adapter for distribution across instances.

function outboxRecord(event: ApplicationEvent, app: Application) {
  return {
    id: `${event.provider}:${event.eventId}:application.updated`,
    topic: 'application.updated',
    applicationId: app.id,
    payload: { applicationId: app.id, version: app.version },
    publishedAt: null,
    attempts: 0,
  };
}
// Insert alongside application update and job completion.
// Publisher claims with a lease, publishes, then marks sent.
// Failed sends retry with backoff; expired leases recover crashes.
// Repeated notifications are safe: clients compare versions/refetch.