URL Redirect

Por padrão, quando o assinante termina de assinar, ele cai numa página de sucesso da ForSign. Com URL Redirect, você o manda direto para sua página — confirmação personalizada, próximo passo do onboarding, status no seu sistema, o que fizer sentido.

Por metadado

Adicione @module/redirect-url em metadata na criação.

Placeholders

{operationId} e {externalId} substituídos no momento do redirect.

HTTPS recomendado

http é aceito, mas browsers podem bloquear o redirect.

Não-confiável

Valores na URL podem ser modificados pelo usuário — sempre re-valide.

Como configurar

A configuração é feita na criação da operação, via metadados. Adicione o metadado @module/redirect-url no payload:

{
  "name": "Operação exemplo",
  "metadata": [
    {
      "key": "@module/redirect-url",
      "value": "https://meusite.com/obrigado/{externalId}/{operationId}"
    }
  ]
}

A ForSign lê esse metadado no fim da assinatura e substitui os placeholders na URL antes de redirecionar.

Fallback global. Se você não passa o metadado mas tem uma URL de redirect global configurada na sua conta, ela é usada. O metadado da operação tem precedência sobre essa configuração.

Placeholders disponíveis

Placeholder	O que é	Comportamento se ausente
`{operationId}`	ID da operação (ex.: `5538`)	Sempre substituído (a operação sempre tem ID)
`{externalId}`	Campo livre que você passa em `externalId` no `POST /operation`	Não é substituído se você não definir `externalId` — a string `{externalId}` fica literal na URL

Só esses dois placeholders são suportados pelo módulo. Outras chaves entre chaves ({memberId}, {name} etc.) não são substituídas — caem literais na URL final.

Exemplo com `externalId`

{
  "name": "Onboarding cliente 123",
  "externalId": "user-123",
  "metadata": [
    {
      "key": "@module/redirect-url",
      "value": "https://meusite.com/status/{externalId}/{operationId}"
    }
  ]
}

Após a assinatura, o assinante é redirecionado para https://meusite.com/status/user-123/5538.

Validação de URL

A configuração global de URL de redirect da sua conta exige:

URL absoluta.
Esquema http ou https.

O metadado de operação não passa por essa validação — você é responsável por mandar uma URL válida. Uma URL malformada vai cair direto na página, o que pode quebrar o redirect (o browser nem chega a navegar).

Sempre use HTTPS. Browsers modernos podem bloquear o redirect ou exibir avisos de mistura de conteúdo se a URL for HTTP. URLs sem esquema (ex.: meusite.com/x) não funcionam — precisa ser absoluta.

Casos de uso comuns

Página de obrigado personalizada (sem dado)

https://meusite.com/obrigado

Status da operação no seu sistema

https://meusite.com/contratos/{operationId}

Próxima etapa do onboarding

https://meusite.com/onboarding/passo-3?contract={externalId}

Multi-tenant

https://app.meusite.com/{externalId}/contratos/{operationId}/concluido

Boas práticas e segurança

externalId é entrada do usuário até prova em contrário. Ele aparece na URL pública, é visível para o assinante, e pode ser modificado por ele antes de chegar ao seu sistema:

Use IDs opacos (UUID v4) em vez de IDs sequenciais ou e-mails.
Re-valide no servidor ao receber o callback — não confie no valor recebido pela URL.
Não coloque dados sensíveis (token, e-mail, CPF) em query string — fica em histórico do browser, logs de proxy, referrer.

Valide a URL no seu lado antes de mandar pra ForSign — uma URL malformada faz o assinante cair numa página quebrada.
Use {operationId} como referência se a página de destino precisa do estado da operação: consulte via API ao receber o usuário (com sua X-Api-Key, server-side).
Não exponha lógica de negócio em externalId — trate-o como um ponteiro opaco para o registro real no seu banco.
HTTPS sempre — proteja contra MITM e evite avisos do browser.