Correlação de Eventos

Ponto de entrada para um sistema externo entregar uma correlação — o gatilho que destrava um nó EVENT_CATCHER ou um BOUNDARY_INTERRUPTIVE_CATCH_EVENT (ver EVENT_CATCHER e EVENT_THROWER e Boundary Catch Event no Guia do Desenvolvedor) — sem que quem chama precise conhecer processInstanceId ou taskId, só a chave técnica de correlação. É o endpoint típico por trás de um webhook de terceiro ("pedido pago", "documento assinado", "proposta recebida").

POST /events/correlate/{correlationKey}
Content-Type: application/json

Requer KikwiflowEngine no contexto.

Requisição

{
  "variables": {
    "valorPago": { "name": "valorPago", "value": 1500.00 }
  }
}

correlationKey vai na URL — o mesmo padrão de PUT /external-tasks/{id}/claim/{assignee}. O corpo carrega só as variáveis a anexar à instância no momento da correlação; variables é opcional.

Resposta

202 Accepted com a ProcessInstance atualizada — a correlação é aplicada e o fluxo avança de forma síncrona dentro desta mesma chamada, igual a completeExternalTask.

404 (NOT_FOUND, via TaskNotFoundException) para qualquer caso de "ninguém está esperando essa chave agora": a chave nunca existiu, já foi consumida por uma correlação anterior, uma corrida ANY de um EVENT_CATCHER em grupo já foi decidida por outra chave, o nó foi cancelado por um boundary, ou a chave existe mas pertence a outro tenant. A resposta não distingue esses casos entre si — todos chegam como o mesmo 404.

:::tip Idempotência natural Reenviar a mesma correlação depois que ela já foi processada devolve 404, não um sucesso repetido — a ExternalTask associada já foi removida na primeira entrega. Útil para clientes que fazem retry automático em webhooks (ex.: provedores de pagamento): o segundo POST não duplica efeito, só falha de forma previsível. :::