> 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/api-http/post-api-v1-fire-eventname-instanceid.md).

# POST /api/v1/fire/{eventName}/{instanceId}

Dispara um evento externo. A execução que estiver parada em `SkailTask.WaitForEvent` com o mesmo nome e o mesmo instance id é acordada e recebe o corpo como payload.

## Rota

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

{ ...payload do evento em JSON... }
```

## Parâmetros do caminho

| Segmento     | O que é                                                                                                     | Exemplo                                |
| ------------ | ----------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `eventName`  | Nome do evento. Precisa ser idêntico ao primeiro argumento do `WaitForEvent`                                | `PAGAMENTO_CONFIRMADO`                 |
| `instanceId` | Identifica qual instância está sendo aguardada. Precisa ser idêntico ao segundo argumento do `WaitForEvent` | `8f2c3a10-0000-4000-8000-000000000001` |

É esse par que correlaciona o disparo à espera. Nome com caixa diferente, ou instance id com um caractere a mais, e o evento não encontra a espera. Use um id de negócio estável nos dois lados (o mesmo id da fatura que a function recebeu), e mantenha os nomes de evento como constantes compartilhadas.

## Corpo

O payload do evento em JSON. Ele é desserializado no tipo `T` do `WaitForEvent<T>` correspondente; para um `WaitForEvent` sem tipo (só sinal), o corpo é ignorado e pode ser `{}`.

```csharp
// Na function
var confirmacao = await SkailTask.WaitForEvent<ConfirmacaoPagamento>("PAGAMENTO_CONFIRMADO", faturaId.ToString());

// O corpo do fire precisa desserializar em ConfirmacaoPagamento
public record ConfirmacaoPagamento(bool Aprovado, string TransacaoId, string? MotivoRecusa);
```

```json
{ "aprovado": true, "transacaoId": "txn_123", "motivoRecusa": null }
```

## Comportamento

Se existe uma execução esperando por `eventName` + `instanceId`: o payload é entregue, a execução é acordada e continua a partir do `await`. Se há mais de um `WaitForEvent` com o mesmo nome e id na mesma execução, eles são atendidos em ordem, um fire para cada.

Se não existe espera ainda: o skail entrega o evento assim que uma execução alcançar o `WaitForEvent` correspondente. Isso cobre o caso comum do webhook que chega antes de a function ter avançado até a espera.

O contexto de rastreamento (traceparent) da espera é preservado: no Monitor, o disparo aparece ligado à execução que ele acordou.

## Resposta

Sucesso: resposta `2xx`. Erros: ver [Autenticação e headers](/construir/api-http/autenticacao-e-headers.md).

## Exemplos

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST "https://SEU_SKAIL_BASE_URL/api/v1/fire/PAGAMENTO_CONFIRMADO/8f2c3a10-0000-4000-8000-000000000001" \
  -H "Content-Type: application/json" \
  -H "skail-key: SUA_SKAIL_KEY" \
  -H "Skail-namespace: SEU_NAMESPACE" \
  -d '{ "aprovado": true, "transacaoId": "txn_123" }'
```

{% endtab %}

{% tab title="C# (webhook ASP.NET)" %}

```csharp
using System.Net.Http.Json;

[ApiController]
[Route("webhooks/pagamentos")]
public class PagamentosWebhookController : ControllerBase
{
    private readonly HttpClient _skail; // headers skail-key e Skail-namespace já configurados

    public PagamentosWebhookController(IHttpClientFactory factory)
        => _skail = factory.CreateClient("skail");

    [HttpPost]
    public async Task<IActionResult> Receber(ConfirmacaoPagamento confirmacao, [FromQuery] Guid faturaId)
    {
        var response = await _skail.PostAsJsonAsync(
            $"/api/v1/fire/PAGAMENTO_CONFIRMADO/{faturaId}",
            confirmacao);

        response.EnsureSuccessStatusCode();
        return Ok();
    }
}
```

{% endtab %}

{% tab title="Node.js" %}

```typescript
const url = `${SKAIL_BASE_URL}/api/v1/fire/PAGAMENTO_CONFIRMADO/${faturaId}`;

await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'skail-key': SKAIL_KEY,
    'Skail-namespace': SKAIL_NAMESPACE,
  },
  body: JSON.stringify({ aprovado: true, transacaoId: 'txn_123' }),
});
```

{% endtab %}
{% endtabs %}

## O disparo não é um método do SDK

Não existe `SkailTask.FireEvent`. Quem dispara é o sistema que tem a informação (o endpoint do webhook, a tela de aprovação, um job do legado, um serviço em outra linguagem), pela API HTTP. Se o disparo precisar acontecer de dentro de uma execução durável, faça a chamada HTTP dentro de um `[SkailCommand]`, como qualquer integração externa.

## Veja também

[Como disparar um evento pela API HTTP](/construir/escrever-fluxos/como-disparar-um-evento-pela-api-http.md), [WaitForEvent](/construir/sdk-.net/waitforevent.md), [Eventos externos e correlação](/aprender/fundamentos/eventos-externos-e-correlacao.md), [Como esperar com timeout](/construir/escrever-fluxos/como-esperar-com-timeout.md).