> 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/aprender/fundamentos/eventos-externos-e-correlacao.md).

# Eventos externos e correlação

Uma function pode parar e esperar algo que acontece fora dela: um webhook, uma aprovação, o retorno de outro sistema. Esta página explica como a espera e o disparo se encontram, o que acontece quando o evento chega antes ou nunca chega, e quem dispara por onde.

## Duas pontas

Na function, `SkailTask.WaitForEvent(nome, instanceId)` hiberna a execução até chegar um evento com aquele nome e aquele instance id. Do lado de fora, quem tem a informação faz `POST /api/v1/fire/{nome}/{instanceId}` na API HTTP do skail, com o payload em JSON. O disparo não é um método do SDK: é uma chamada HTTP, feita de qualquer sistema, em qualquer linguagem.

```csharp
var confirmacao = await SkailTask.WaitForEvent<ConfirmacaoPagamento>(Eventos.PagamentoConfirmado, faturaId.ToString());
```

```http
POST /api/v1/fire/PAGAMENTO_CONFIRMADO/8f2c3a10-0000-4000-8000-000000000001
```

## O par que correlaciona

O nome identifica o tipo do evento; o instance id identifica qual instância está sendo aguardada. Os dois precisam ser idênticos nos dois lados, caractere a caractere. É só isso que liga o disparo à espera: o skail não olha o conteúdo do payload para decidir para quem entregar.

Por isso as duas regras práticas: o nome vive em uma constante compartilhada, nunca em strings literais espalhadas; e o instance id é um id de negócio estável que os dois lados já conhecem (o id da fatura, do pedido, da solicitação), nunca algo gerado na hora.

Quando há mais de um `WaitForEvent` com o mesmo nome e id na mesma execução, eles são atendidos em ordem: o primeiro fire libera a primeira espera, o segundo libera a segunda.

## O evento chega antes da espera

É comum: o webhook do gateway responde em segundos, enquanto a function ainda está em um passo anterior. O evento fica aguardando e é entregue assim que a execução alcançar o `WaitForEvent` correspondente. Você não precisa se preocupar com a ordem.

## O evento nunca chega

Se ninguém dispara, a execução fica hibernada indefinidamente. No Monitor ela aparece como aguardando evento, com o nome e o id esperados. Isso é bom para diagnosticar (nome divergente, id errado, webhook que não foi entregue) e ruim se ninguém está olhando. Por isso toda espera leva um prazo: um `WhenAny` entre o `WaitForEvent` e um `Delay`, e a function decide o que fazer no timeout. O padrão está em [Como esperar com timeout](/construir/escrever-fluxos/como-esperar-com-timeout.md).

## O payload

`WaitForEvent<T>` devolve o corpo do fire desserializado em `T` com `System.Text.Json`. `WaitForEvent` sem tipo só sinaliza; o corpo é ignorado. Mantenha `T` um record pequeno, com o que a function precisa para decidir, e deixe o resto para um command carregar depois.

## Quem dispara, por onde

O endpoint que recebe o webhook do gateway. A tela onde uma pessoa aprova (o BFF faz o fire). Um job do legado quando termina um lote. Um serviço em Node.js, Java ou Python. Todos fazem o mesmo `POST`, com `skail-key` e `Skail-namespace` do environment. Se o disparo precisar acontecer de dentro de uma execução durável, a chamada HTTP fica em um `[SkailCommand]`, como qualquer integração externa.

## Próximos passos

[Como disparar um evento pela API HTTP](/construir/escrever-fluxos/como-disparar-um-evento-pela-api-http.md) tem o webhook completo em C#. A referência de [WaitForEvent](/construir/sdk-.net/waitforevent.md) e de [POST /api/v1/fire](/construir/api-http/post-api-v1-fire-eventname-instanceid.md) traz assinaturas, corpo e erros. [Human-in-the-loop](/construir/padroes-e-antipadroes/human-in-the-loop.md) é o padrão para aprovações.