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

# POST fire

Dispara um evento externo.

A execução que estiver parada em uma espera por evento 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
Authorization: Bearer SUA_SKAIL_KEY
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 da espera por evento                                | `PAGAMENTO_CONFIRMADO`                 |
| `instanceId` | Identifica qual instância está sendo aguardada. Precisa ser idêntico ao segundo argumento da espera por evento | `8f2c3a10-0000-4000-8000-000000000001` |

É esse par que correlaciona o disparo à espera. Se o nome tiver caixa diferente ou o instance id tiver um caractere a mais, 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. A espera por evento correspondente recebe esse payload. Em C#, ele é desserializado no `T` de `WaitForEvent<T>`, e uma espera sem tipo (só sinal) ignora o corpo, que pode ser `{}`; em TypeScript, a espera devolve o JSON do corpo como o `T` de `Skail.waitForEvent<T>`, com as datas em string ISO-8601.

Os nomes dos campos precisam ter a mesma caixa das propriedades do tipo que a function recebe: com `Aprovado` no tipo, o campo `aprovado` no JSON não preenche a propriedade, que fica com o valor padrão (`false`), e a execução segue sem erro. Em C#, o `PostAsJsonAsync` sem opções manda os nomes em camelCase; passe `JsonSerializerOptions.Default`.

Em C#, uma propriedade enum do tipo vai como número no JSON (`"Status": 0`, não `"Status": "Aprovado"`). Se quem dispara só tem o texto (um sistema em TypeScript, por exemplo), declare a propriedade como `string` no tipo C#, como o `Motivo` de [Cobrança, recorrência e split de pagamento](/construa/casos-de-uso/cobranca-recorrencia-e-split-de-pagamento.md). Ver [Passar dados entre função e commands](/construa/como-fazer/passar-dados-entre-funcao-e-commands.md).

{% tabs %}
{% tab title="C#" %}

```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);
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
import { Skail, SkailFunction } from "@skail/runtime";

export interface ConfirmacaoPagamento {
  Aprovado: boolean;
  TransacaoId: string;
  MotivoRecusa: string | null;
}

export class FaturaService {
  @SkailFunction()
  async AguardarPagamento(faturaId: string): Promise<void> {
    // Na function
    const confirmacao = await Skail.waitForEvent<ConfirmacaoPagamento>("PAGAMENTO_CONFIRMADO", faturaId);
    console.info(confirmacao.TransacaoId);
  }
}

// O corpo do fire precisa desserializar em ConfirmacaoPagamento
```

{% endtab %}
{% endtabs %}

```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 uma espera com o mesmo nome e id na mesma execução, elas são atendidas em ordem, um fire para cada.

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

{% hint style="info" %}
O contexto de rastreamento (traceparent) da espera é preservado: no Monitor, o disparo aparece ligado à execução que ele acordou.
{% endhint %}

## Resposta

Sucesso: resposta `2xx`. Erros: ver [Autenticação e headers](/referencia/api-http/autenticacao.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 "Authorization: Bearer SUA_SKAIL_KEY" \
  -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;
using System.Text.Json;

[ApiController]
[Route("webhooks/pagamentos")]
public class PagamentosWebhookController : ControllerBase
{
    private readonly HttpClient _skail; // headers Authorization, 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,
            JsonSerializerOptions.Default);

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

{% endtab %}

{% tab title="TypeScript" %}

```typescript
export interface ConfirmacaoPagamento {
  Aprovado: boolean;
  TransacaoId: string;
  MotivoRecusa: string | null;
}

export interface SkailHttp {
  post(path: string, body: unknown): Promise<Response>;
}

export class PagamentosWebhookController {
  constructor(private readonly skail: SkailHttp) {}

  // o corpo precisa chegar com os nomes de ConfirmacaoPagamento (Aprovado, TransacaoId, MotivoRecusa);
  // se o gateway usa outros nomes, monte o objeto campo a campo antes do fire
  async Receber(confirmacao: ConfirmacaoPagamento, faturaId: string): Promise<{ status: 200 }> {
    const response = await this.skail.post(
      `/api/v1/fire/PAGAMENTO_CONFIRMADO/${faturaId}`,
      confirmacao,
    );

    if (!response.ok) throw new Error(`fire falhou: ${response.status}`);
    return { status: 200 };
  }
}
```

{% endtab %}
{% endtabs %}

## O disparo é uma chamada HTTP

Em C#, 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), com uma chamada HTTP a esta rota. Se o disparo precisar acontecer de dentro de uma execução durável, faça a chamada HTTP dentro de um command, como qualquer integração externa.

## Veja também

[Como disparar um evento pela API HTTP](/construa/como-fazer/disparar-um-evento-pela-api.md), [WaitForEvent](/referencia/sdk-csharp/waitforevent.md) (referência do SDK C#), [Eventos externos e correlação](/construa/conceitos/eventos-externos-e-correlacao.md), [Como esperar com timeout](/construa/como-fazer/esperar-um-evento-com-prazo.md).