FaunaDB Eventhooks: filtering alert conditions without duplicate notifications

Direct Answers

1. Conditional logic inside the Eventhook function is the intended suppression mechanism. FaunaDB does not provide a declarative filter at the hook configuration level. You write an FQL function that inspects the event payload (the changed document, operation type, etc.) and returns null or an empty result when criteria are not met. This silently suppresses the external call without affecting the originating transaction.

2. The external call does not consume the source transaction's time budget. Eventhooks are asynchronous: they fire after the triggering transaction commits. A slow or failing HTTP call cannot roll back the write or push the original transaction toward its timeout. The hook itself has its own execution ceiling (typically a few seconds), but it is decoupled from the writer's latency.

3. Receiver-side idempotency is the only reliable safeguard against duplicates. FaunaDB guarantees at-least-once delivery. Network retries, internal restarts, or transient endpoint failures can cause the same event to be delivered multiple times. The standard pattern is to include a stable identifier—such as the transaction ID (event.transaction) or the document's version timestamp—in the payload, and have the receiver deduplicate on that key.

Implementation Pattern

CreateFunction({
  name: "alert_on_status_change",
  body: Query(Lambda(["event"],
    Let({
      doc: Select(["data", "document"], Var("event")),
      prev: Select(["data", "prev"], Var("event")),
      shouldAlert: Not(Equals(Select(["data", "status"], Var("doc")),
                               Select(["data", "status"], Var("prev"))))
    },
    If(Var("shouldAlert"),
      Do(
        Call("http_post", {
          url: "https://alerts.example.com/ingest",
          headers: { "Content-Type": "application/json" },
          body: {
            txnId: Select(["transaction"], Var("event")),
            docRef: Select(["ref"], Var("doc")),
            newStatus: Select(["data", "status"], Var("doc"))
          }
        }),
        null
      ),
      null
    )
  ))
}))

The If branch returns null when the condition fails, which tells FaunaDB "nothing to deliver" for this event. No HTTP request is made.

Verification Steps

1. Create the function above and attach it as an Eventhook on the target collection.
2. Update a document without changing status; confirm no request reaches your endpoint (check logs or a request bin).
3. Update the same document with a new status; confirm a single POST arrives with the expected txnId.
4. Simulate a slow endpoint (e.g., a 10 s delay) and observe that the originating write returns immediately while the hook retries in the background.

Open Diagnostic Detail

What is the expected peak write throughput on the collection? If it exceeds a few hundred events per second, you may need to batch or queue deliveries outside the hook to avoid overwhelming the endpoint or hitting FaunaDB's concurrent hook execution limits.