Signals and external events

Handlers sometimes need to receive input after their invocation has started. Restate provides three durable coordination primitives for this:

Primitive	Address	Resolution	Use for
Signal	Invocation ID and signal name	Can be resolved multiple times. Each wait receives the next resolution.	Communication between ongoing invocations, agent steering, and human approvals
Awakeable	Generated unique ID	Resolved or rejected once	Convenient shorthand for external callbacks and one-shot task tokens
Workflow promise	Workflow key and promise name	Resolved or rejected once. The result can be retrieved multiple times by all handlers of the workflow.	Coordination between handlers of the same workflow

All three survive retries and process restarts. When an invocation has nothing else to do while waiting, Restate can suspend it and resume it when the next result arrives.

Signals

Signals deliver durable notifications to an ongoing invocation. A signal is identified by the target invocation ID and a name. The same named signal can be resolved multiple times. Each await of the signal receives the next resolution.

Wait for a signal

Boolean approval = Restate.signal("approval", Boolean.class).await();

var approval = signal<Boolean>("approval").await()

Resolve a signal

To resolve a signal, you need the target invocation ID. You can get it from a call or send handle, or read the current invocation’s ID from the handler request and pass it to the sender.

Restate.invocationHandle(req.invocationId()).signal("steer").resolve(String.class, req.text());

invocationHandle<Unit>(req.invocationId).signal("steer").resolve(req.text)

Use reject() instead of resolve() to deliver a terminal failure to the waiting invocation.

Wait for repeated signals

A signal can be resolved multiple times. Repeatedly call the signal API to wait for the next resolution of a named signal:

@Handler
public String reviseUntilDone(String topic) {
  String draft = "Research notes for " + topic;
  while (true) {
    String text = Restate.signal("steer", String.class).await();
    if (text.equals("done")) {
      return draft;
    }
    draft = draft + "\n" + text;
  }
}

@Handler
suspend fun reviseUntilDone(topic: String): String {
  var draft = "Research notes for $topic"
  while (true) {
    val text = signal<String>("steer").await()
    if (text == "done") {
      return draft
    }
    draft = "$draft\n$text"
  }
}

A signal can arrive before or after the invocation starts waiting for it. Restate stores each resolution durably until the invocation receives it.

Awakeables

An awakeable is a convenient shorthand for a one-shot signal. It has a generated unique ID that an external system can resolve or reject through Restate, similar to a task token.

Creating and waiting for awakeables

Create an awakeable - Get a unique ID and awaitable result
Send the ID externally - Pass the awakeable ID to your external system
Wait for result - Your handler suspends until the external system responds

// Create awakeable and get unique ID
Awakeable<String> awakeable = Restate.awakeable(String.class);
String awakeableId = awakeable.id();

// Send ID to external system (email, queue, webhook, etc.)
Restate.run("request-human-review", () -> requestHumanReview(name, awakeableId));

// Handler suspends here until external completion
String review = awakeable.await();

// Create awakeable and get unique ID
val awakeable = awakeable<String>()
val awakeableId = awakeable.id

// Send ID to external system (email, queue, webhook, etc.)
runBlock { requestHumanReview(awakeableId) }

// Handler suspends here until external completion
val review = awakeable.await()

Serialization

To customize serialization, visit the docs.

Note that if you wait for an awakeable in an exclusive handler in a Virtual Object, all other calls to this object will be queued.

Resolving or rejecting an awakeable

External processes complete awakeables in two ways:

Resolve with success data → handler continues normally
Reject with error reason → throws a terminal error in the waiting handler

Via SDK (from other handlers)

Resolve:

// Complete with success data
Restate.awakeableHandle(awakeableId).resolve(String.class, "Looks good!");

// Complete with success data
awakeableHandle(awakeableId).resolve("Looks good!")

Reject:

// Complete with error
Restate.awakeableHandle(awakeableId).reject("This cannot be reviewed.");

// Complete with error
awakeableHandle(awakeableId).reject("This cannot be reviewed.")

Via HTTP API

External systems can complete awakeables using Restate’s HTTP API: Resolve with data:

curl localhost:8080/restate/awakeables/sign_1PePOqp/resolve \
--json '"Looks good!"'

Reject with error:

curl localhost:8080/restate/awakeables/sign_1PePOqp/reject \
-H 'content-type: text/plain' \
-d 'Review rejected: insufficient documentation'

Workflow promises

A workflow promise belongs to a workflow key and has a logical name. It can be resolved or rejected once, and its result can be retrieved multiple times by all handlers of the workflow during the workflow retention period. Use this to:

Have shared handlers interact with the workflow run handler
Have one or multiple handlers wait for events emitted by the run handler

After a workflow’s run handler completes, other handlers can still be called for up to 24 hours (default). The results of resolved workflow promises remain available during this time. Update the retention time via the service configuration.

Get and wait for a workflow promise

Create a workflow promise key:

private static final DurablePromiseKey<String> REVIEW_PROMISE =
    DurablePromiseKey.of("review", String.class);

val REVIEW_PROMISE = durablePromiseKey<String>("review")

Wait for a workflow promise by name:

String review = Restate.promise(REVIEW_PROMISE).future().await();

val review: String = promise(REVIEW_PROMISE).future().await()

Your workflow can suspend until the workflow promise is resolved or rejected.

Resolve or reject a workflow promise

Resolve or reject it from any handler of the same workflow:

Restate.promiseHandle(REVIEW_PROMISE).resolve(review);

promiseHandle(REVIEW_PROMISE).resolve(review)

Complete workflow example

@Workflow
public class ReviewWorkflow {
  private static final DurablePromiseKey<String> REVIEW_PROMISE =
      DurablePromiseKey.of("review", String.class);


  @Workflow
  public String run(String documentId) {
    // Send document for review
    Restate.run("ask-review", () -> askReview(documentId));

    // Wait for external review submission
    String review = Restate.promise(REVIEW_PROMISE).future().await();

    // Process the review result
    return processReview(documentId, review);
  }

  @Shared
  public void submitReview(String review) {
    // Resolve the workflow promise awaited by the run handler
    Restate.promiseHandle(REVIEW_PROMISE).resolve(review);
  }
}

@Workflow
class ReviewWorkflow {

  companion object {
    val REVIEW_PROMISE = durablePromiseKey<String>("review")
  }

  @Workflow
  suspend fun run(documentId: String): String {
    // Send document for review
    runBlock { askReview(documentId) }

    // Wait for external review submission
    val review: String = promise(REVIEW_PROMISE).future().await()

    // Process the review result
    return processReview(documentId, review)
  }

  @Shared
  suspend fun submitReview(review: String) {
    // Resolve the workflow promise awaited by the run handler
    promiseHandle(REVIEW_PROMISE).resolve(review)
  }
}

Choose a primitive

Use a signal when another Restate invocation needs to send one or more notifications to an invocation that is already running. Use an awakeable when an external system needs a unique, one-shot callback token that it can complete through Restate’s HTTP API. Use a workflow promise when the value belongs to a workflow and should remain retrievable by any of its handlers for the workflow retention period. For long waits, combine the primitive with a durable timer to implement a timeout. Handle rejection when the sender can report a terminal failure.

SDKs

Services

Restate Cloud

Restate BYOC

Self-hosted Restate

References

Signals and external events

Signals

Wait for a signal

Resolve a signal

Wait for repeated signals

Awakeables

Creating and waiting for awakeables

Resolving or rejecting an awakeable

Via SDK (from other handlers)

Via HTTP API

Workflow promises

Get and wait for a workflow promise

Resolve or reject a workflow promise

Complete workflow example

Choose a primitive

​Signals

​Wait for a signal

​Resolve a signal

​Wait for repeated signals

​Awakeables

​Creating and waiting for awakeables

​Resolving or rejecting an awakeable

​Via SDK (from other handlers)

​Via HTTP API

​Workflow promises

​Get and wait for a workflow promise

​Resolve or reject a workflow promise

​Complete workflow example

​Choose a primitive

Signals

Wait for a signal

Resolve a signal

Wait for repeated signals

Awakeables

Creating and waiting for awakeables

Resolving or rejecting an awakeable

Via SDK (from other handlers)

Via HTTP API

Workflow promises

Get and wait for a workflow promise

Resolve or reject a workflow promise

Complete workflow example

Choose a primitive