Hooks de instalação

Hooks de instalação são funções de lógica especiais que são executadas durante o ciclo de vida de instalação, atualização ou desinstalação. Elas compartilham o mesmo runtime de handler que as logic functions normais, mas são declaradas com suas próprias funções de definição e ficam fora do modelo de gatilhos normal (HTTP, cron, eventos de banco de dados). Hooks de instalação recebem um InstallPayload ({ previousVersion?: string; newVersion: string } — previousVersion é undefined em uma instalação nova); o hook de desinstalação recebe um UninstallPayload ({ version?: string } — a versão que está sendo removida). Cada app pode definir no máximo um de cada hook (pre-instalação, pós-instalação, desinstalação). A geração do manifesto apresentará erro se mais de um de qualquer tipo for detectado.

┌─────────────────────────────────────────────────────────────┐
│ install flow                                                │
│                                                             │
│   upload package → [pre-install] → metadata migration →     │
│   generate SDK → [post-install]                             │
│                                                             │
│                  old schema visible    new schema visible   │
└─────────────────────────────────────────────────────────────┘

Visão geral

	`definePreInstallLogicFunction`	`definePostInstallLogicFunction`
Execuções	Antes da migração de metadados — o esquema e os dados anteriores ainda estão intactos	Após a migração e a geração do SDK — o novo esquema está em vigor
Execução	Sempre síncrona; bloqueia a instalação	Assíncrona por padrão (em fila, 3 novas tentativas); modo síncrono por opt-in via `shouldRunSynchronously: true`
Em caso de falha	A instalação é abortada antes de qualquer alteração de esquema	Assíncrono: novas tentativas até 3 vezes. Síncrono: o chamador recebe `POST_INSTALL_ERROR` (as alterações de esquema não são revertidas)
Uso típico	Fazer backup ou corrigir dados que uma migração poderia perder; recusar uma atualização arriscada lançando uma exceção	Popular dados padrão, configurar o workspace, registrar recursos externos

Regra geral: use post-install como padrão. Recurra à pré-instalação somente quando a própria migração for destrutiva e você precisar interceptar o estado anterior antes que ele desapareça.

Você quer…	Usar
Popular dados, configurar o workspace, registrar recursos externos	`post-install`
Trabalho de longa duração que não deve bloquear a resposta da instalação	`post-install` (modo assíncrono padrão, com novas tentativas do worker)
Configuração rápida da qual o chamador depende imediatamente após o retorno da instalação	`post-install` com `shouldRunSynchronously: true`
Ler ou fazer backup de dados que a próxima migração perderia	`pre-install`
Rejeitar uma atualização que corromperia dados existentes	`pre-install` (lançar uma exceção no manipulador)
Reconciliação em cada atualização	Qualquer um dos hooks com `shouldRunOnVersionUpgrade: true`

Comportamento compartilhado por ambos os hooks

A configuração é uma config de defineLogicFunction menos as configurações de gatilho, mais shouldRunOnVersionUpgrade.
Quando é executado: apenas em instalações novas, por padrão. Defina shouldRunOnVersionUpgrade: true para também executar em atualizações. Use previousVersion / newVersion para ramificar com base no caminho de atualização.
Idempotência é importante: o post-install assíncrono pode ser executado novamente, e qualquer um dos hooks é reexecutado em atualizações quando shouldRunOnVersionUpgrade está ativado.
O ambiente usual de logic-function (APPLICATION_ID, APP_ACCESS_TOKEN, API_URL) é injetado, para que você possa chamar a Twenty API com o token do seu app.
O hook é anexado automaticamente ao manifesto da aplicação em tempo de build (preInstallLogicFunction / postInstallLogicFunction) — nada para referenciar em defineApplication().
O timeoutSeconds padrão é 300 para permitir tarefas de configuração mais longas, como o pré-carregamento de dados.
Não é executado em modo de desenvolvimento: yarn twenty dev ignora o fluxo de instalação e sincroniza os arquivos diretamente, portanto os hooks nunca são executados ali. Em vez disso, acione-os manualmente:

yarn twenty dev:function:exec --postInstall
yarn twenty dev:function:exec --preInstall

definePostInstallLogicFunction

É executada depois que a migração de metadados do workspace é aplicada

É executado depois que seu app termina de ser instalado: metadados sincronizados, cliente SDK gerado, novo esquema disponível para consulta. Exemplo — popular um registro padrão em instalações novas:

src/logic-functions/post-install.ts

import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
import { CoreApiClient } from 'twenty-client-sdk/core';

const handler = async ({ previousVersion }: InstallPayload): Promise<void> => {
  if (previousVersion) return; // fresh installs only

  const client = new CoreApiClient();
  await client.mutation({
    createPostCard: {
      __args: { data: { name: 'Welcome to Postcard', content: 'Your first card!' } },
      id: true,
    },
  });
};

export default definePostInstallLogicFunction({
  universalIdentifier: 'f7a2b9c1-3d4e-5678-abcd-ef9876543210',
  name: 'post-install',
  description: 'Seeds a welcome post card after install.',
  timeoutSeconds: 300,
  shouldRunOnVersionUpgrade: false,
  shouldRunSynchronously: false,
  handler,
});

A flag shouldRunSynchronously controla o modelo de execução:

false (padrão) — colocado em fila na message queue (retryLimit: 3) e executado por um worker. A resposta da instalação retorna assim que o job é colocado na fila. Use para trabalhos de longa duração — popular grandes conjuntos de dados, APIs lentas de terceiros.
true — executado inline durante o fluxo de instalação. A requisição de instalação fica bloqueada até que o handler termine; um erro lançado aparece como POST_INSTALL_ERROR para o chamador (sem novas tentativas). Use para trabalhos rápidos que precisam ser concluídos antes da resposta. A migração já foi aplicada neste ponto, portanto uma falha não reverte as alterações de esquema — ela apenas expõe o erro.

definePreInstallLogicFunction

É executada antes que a migração de metadados do workspace seja aplicada

É executado antes da migração de metadados, contra o esquema anterior — o lugar certo para fazer backup de dados que uma migração poderia perder ou para recusar uma atualização arriscada. Antes de executar, o servidor realiza uma “sincronização simplificada” puramente aditiva que registra apenas a função de pré-instalação da nova versão; todo o resto — objetos, campos e dados da versão anterior — permanece intocado quando seu handler é executado.A pré-instalação é sempre síncrona e bloqueia a instalação. Se o handler lançar uma exceção, a instalação é abortada antes de qualquer alteração de esquema — o workspace permanece na versão anterior em um estado consistente. Isto é intencional: a pré-instalação é sua última chance de recusar uma atualização arriscada.Exemplo — copiar os valores de um campo legado antes que a migração o remova:

src/logic-functions/pre-install.ts

import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
import { CoreApiClient } from 'twenty-client-sdk/core';

const handler = async ({ previousVersion, newVersion }: InstallPayload): Promise<void> => {
  // Only the 1.x → 2.x upgrade drops the legacy `notes` field.
  if (!previousVersion?.startsWith('1.') || !newVersion.startsWith('2.')) {
    return;
  }

  const client = new CoreApiClient();
  const { postCards } = await client.query({
    postCards: {
      __args: { filter: { notes: { isNot: null } } },
      edges: { node: { id: true, notes: true } },
    },
  });

  // Copy legacy `notes` into `description` before the migration drops the
  // column. If this fails, the upgrade aborts and the workspace stays on v1.
  for (const { node } of postCards.edges) {
    await client.mutation({
      updatePostCard: {
        __args: { id: node.id, data: { description: node.notes } },
        id: true,
      },
    });
  }
};

export default definePreInstallLogicFunction({
  universalIdentifier: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',
  name: 'pre-install',
  description: 'Backs up legacy notes into description before the v2 migration.',
  timeoutSeconds: 300,
  shouldRunOnVersionUpgrade: true,
  handler,
});

Hook de desinstalação

defineUninstallLogicFunction declara um hook que é executado quando um usuário desinstala seu app. Ele é executado antes que os metadados, dados e código do app sejam removidos — depois que a migration de exclusão é executada, não sobra nada para executar — portanto, seu handler ainda pode consultar os objetos e registros do app. Use-o para limpar recursos externos: desprovisionar recursos de API, excluir bots remanescentes, revogar webhooks. Notas:

O hook é de melhor esforço: ele é executado de forma síncrona, mas uma falha é registrada em log e nunca bloqueia a desinstalação — a limpeza não deve tornar impossível remover um app.
Ele recebe UninstallPayload ({ version?: string } — a versão que está sendo removida).
Ele não é executado quando uma instalação nova com falha é revertida — o app nunca chegou a ser totalmente instalado.
O hook não pode ser executado depois que o app foi removido, então a limpeza externa que depende de dados do app (por exemplo, IDs de bots armazenados em registros) deve ser feita aqui, não em um job externo agendado.
Assim como os hooks de instalação, ele não é executado no modo de desenvolvimento — em vez disso, acione-o manualmente:

yarn twenty dev:function:exec --uninstall

src/logic-functions/uninstall.ts

import { defineUninstallLogicFunction, type UninstallPayload } from 'twenty-sdk/define';
import { CoreApiClient } from 'twenty-client-sdk/core';

const handler = async (_payload: UninstallPayload): Promise<void> => {
  const client = new CoreApiClient();
  const { meetingBots } = await client.query({
    meetingBots: { edges: { node: { id: true, externalBotId: true } } },
  });

  // Delete the provider-side bots so nothing keeps recording after uninstall.
  for (const { node } of meetingBots.edges) {
    await fetch(`https://api.recorder.example/bots/${node.externalBotId}`, {
      method: 'DELETE',
      headers: { Authorization: `Bearer ${process.env.RECORDER_API_KEY}` },
    });
  }
};

export default defineUninstallLogicFunction({
  universalIdentifier: 'b2c3d4e5-6789-01bc-def0-234567890abc',
  name: 'uninstall',
  description: 'Deletes remaining recorder bots when the app is uninstalled.',
  timeoutSeconds: 300,
  handler,
});

Visão Geral

Aplicativos

API

Auto-Anfitrião

Contribuir

Visão geral

Comportamento compartilhado por ambos os hooks

Hook de desinstalação

​Visão geral

​Comportamento compartilhado por ambos os hooks

​Hook de desinstalação

Visão geral

Comportamento compartilhado por ambos os hooks

Hook de desinstalação