> For the complete documentation index, see [llms.txt](https://docs.skail.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skail.dev/construir/sdk-.net/waitforevent.md).

# WaitForEvent

Hiberna a execução até que um evento externo com o mesmo nome e o mesmo instance id seja disparado pela API HTTP. Esta é a referência da primitiva; o conceito está em [Eventos externos e correlação](/aprender/fundamentos/eventos-externos-e-correlacao.md) e o guia em [Como disparar um evento pela API HTTP](/construir/escrever-fluxos/como-disparar-um-evento-pela-api-http.md).

## Assinaturas

```csharp
public static SkailTask WaitForEvent(string eventName, string eventInstanceId);
public static SkailTask<T> WaitForEvent<T>(string eventName, string eventInstanceId);
```

| Parâmetro         | Tipo              | Descrição                                                                                                                                           |
| ----------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eventName`       | `string`          | Nome do evento. Identifica o tipo (`"PAGAMENTO_CONFIRMADO"`). Precisa ser idêntico ao segmento `{eventName}` do fire. Use constantes compartilhadas |
| `eventInstanceId` | `string`          | Identifica a instância aguardada (o id do pedido). Precisa ser idêntico ao segmento `{instanceId}` do fire. Use um id de negócio estável            |
| `T`               | tipo serializável | Tipo do payload. O corpo JSON do fire é desserializado em `T` com `System.Text.Json`. Na sobrecarga sem `T`, o corpo é ignorado                     |

Só dentro de `[SkailFunction]`.

## Comportamento

Ao alcançar o `await`, o runtime registra o passo com o par nome e instance id e hiberna a execução. Quando um `POST /api/v1/fire/{eventName}/{instanceId}` com o mesmo par chega ao skail, o payload é entregue, a execução é reentregue e a function é retomada a partir do `await`, que devolve o payload desserializado.

Evento que chega antes da espera: o skail o entrega assim que a execução alcançar o `WaitForEvent` correspondente.

Múltiplas esperas com o mesmo par na mesma execução: são atendidas em ordem, um fire para cada. Uma espera criada sem `await` e passada a `WhenAny` pode participar de vários `WhenAny` em sequência (uma espera, vários prazos).

Sem fire, a espera dura indefinidamente. Por isso toda espera leva um prazo com `WhenAny` e `Delay`.

O contexto de rastreamento da espera é preservado até o fire: no Monitor, o disparo aparece ligado à execução acordada.

## Exemplo mínimo

```csharp
public static class Eventos
{
    public const string ConfirmacaoPagamento = "CONFIRMACAO_PAGAMENTO";
}

public record ConfirmacaoPagamento(bool Aprovado, string TransacaoId, string? MotivoRecusa);

[SkailFunction]
public async SkailTask ProcessarPedido(Guid pedidoId)
{
    await RegistrarPedido(pedidoId);

    var confirmacao = SkailTask.WaitForEvent<ConfirmacaoPagamento>(Eventos.ConfirmacaoPagamento, pedidoId.ToString());
    var prazo       = SkailTask.Delay(TimeSpan.FromHours(24));

    if (await SkailTask.WhenAny(confirmacao, prazo) == prazo) { await CancelarPorExpiracao(pedidoId); return; }

    var resultado = await confirmacao;
    if (resultado.Aprovado) await LiberarEnvio(pedidoId);
    else                    await CancelarPedido(pedidoId, resultado.MotivoRecusa);
}
```

O fire correspondente:

```http
POST {SKAIL_BASE_URL}/api/v1/fire/CONFIRMACAO_PAGAMENTO/{pedidoId}
Content-Type: application/json
skail-key: SUA_SKAIL_KEY
Skail-namespace: SEU_NAMESPACE

{ "aprovado": true, "transacaoId": "txn_123" }
```

Só sinal, sem payload: `await SkailTask.WaitForEvent(Eventos.LoteProcessado, loteId.ToString());` e o fire com corpo `{}`.

## Observabilidade

No Monitor, uma execução parada em `WaitForEvent` aparece como aguardando evento, com o nome e o instance id esperados. Isso diagnostica os casos comuns: nome divergente, instance id errado, webhook não entregue. O evento recebido aparece como item próprio na linha do tempo, com o payload.

## Erros relacionados

| Erro                               | Causa                                                                                                             |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Execução aguardando para sempre    | Nome ou instance id diferentes entre espera e fire; fire enviado a outro namespace; sem prazo                     |
| Payload com campos nulos           | Propriedades do JSON não batem com `T`                                                                            |
| Exceção ao desserializar o payload | Corpo do fire incompatível com `T`; use o mesmo record nos dois lados                                             |
| Segunda espera nunca atendida      | Um fire só para duas esperas com o mesmo par; ou uma espera nova criada por iteração quando devia ser reutilizada |

## Veja também

[POST /api/v1/fire](/construir/api-http/post-api-v1-fire-eventname-instanceid.md), [Como esperar com timeout](/construir/escrever-fluxos/como-esperar-com-timeout.md), [Human-in-the-loop](/construir/padroes-e-antipadroes/human-in-the-loop.md), [WhenAll e WhenAny](/construir/sdk-.net/whenall-e-whenany.md).