Hooks & Events Overview

Aerocall lets you customize backend behavior with hooks. Hooks run at specific points in the auth flow (and other flows) so you can add validation, side effects, and integrations without changing Aerocall’s core code.

Types of Hooks

Lifecycle Hooks (inline, per project)

• Implemented as code in your project’s Auth Hooks editor (in the Aerocall admin).
• Functions like beforeSignup, afterSignup, beforeLogin, afterLogin.
• Run inside Aerocall’s runtime with a scoped SDK — you get a safe API to read/write your project’s data and call out to external services in a controlled way.

Project Hooks (webhooks & scripts)

• Configured under Project → Hooks in the admin.
• React to events such as auth.signup, auth.login, auth.password.reset.requested, auth.otp.send, etc.
• Two kinds:
  • Webhooks: HTTP endpoints you host; we send a POST with a JSON payload when the event fires.
  • Script hooks: JavaScript/TypeScript that runs in an isolated environment with the Aerocall Hook SDK (database, cache, queue, etc.).

Each auth endpoint page in the API Reference lists which lifecycle and project hooks run for that endpoint.

Aerocall Hook SDK

When your hook code runs (lifecycle or script), it receives:

• Context: project id, environment, request metadata.
• Payload: endpoint-specific data (e.g. signup body, user object).
• Aerocall — a scoped SDK object with:

Your code cannot access other projects’ data or raw infrastructure. Everything is namespaced to your project. Timeouts and limits apply so one hook cannot block the system.

Managing Hooks in the Admin

1. Viewing hooks per endpoint

In the Aerocall admin:

1. Go to Project → Auth → API & Hooks.
2. You’ll see each auth endpoint (Register, Login, etc.) and which hooks are available.
3. For each endpoint: lifecycle hooks (e.g. beforeSignup, afterSignup) and project events (e.g. auth.signup) with their status: Enabled or Disabled.
4. Click an endpoint to see details and a short summary of what each enabled hook does (AI-generated when available).

2. Editing hook code with AI

• From the endpoint details, click Edit hook on any lifecycle or script hook.
• The hook editor opens with:
  • A code editor (Monaco) with TypeScript types for the hook context and the Aerocall SDK.
  • An AI assistant so you can:
    • Describe what you want (e.g. “Reject signups from free email providers”).
    • Ask the assistant to generate or update the hook.
    • Ask for an explanation of existing hook code.
• Changes are saved as draft until you deploy.

3. Testing hooks for your project

Each hook and each endpoint has a Test tab:

• Unit-style (hook only): Provide sample input JSON, run just the hook logic, and see output, errors, and logs.
• End-to-end (full endpoint with hooks): Choose an endpoint (e.g. POST /auth/register), fill the request body, and run in dry-run (simulate DB and external calls) or live test against your project. You see the request, final response, which hooks ran, and their logs.

Tests are per project, so you see exactly how your project behaves with your hooks enabled.

4. Deploying hook changes

Hook versions follow a simple flow:

1. Draft — You edit and save; this version is not live.
2. Test — Use the Test tab until you’re satisfied.
3. Deploy — Click Deploy to make the current draft the deployed version. All live traffic for this project then uses this version.
4. Rollback — If needed, open Version history and roll back to a previous deployed version.

Summary

• Lifecycle hooks and project hooks (webhooks/scripts) let you customize auth (and other) flows per project.
• Hook code runs with the Aerocall Hook SDK and is scoped to your project only.
• In the admin you view, edit (with AI), test, and deploy hooks; tests are project-specific so you can validate behavior before going live.

For endpoint-level hook details, see each auth endpoint under API Reference → Authentication.