Webhooks

Instead of asking, have the service tell your system when a run finishes:

hook = client.webhooks.create("https://ops.example.com/luna-events")
secret = hook.secret  # shown only this once: keep it
client.webhooks.ping(hook)  # a "ping" event, to try the address out
client.webhooks.list()  # when an event last arrived, or why the latest did not

From then on every finished run of your organisation is sent to the address as a POST of JSON, {"id": ..., "event": "od.completed", "created_at": ..., "data": {"run": {...}}}, data.run being the run as the API shows it.

Event

When

od.completed

A run finished, well or not

od.flagged

A finished run that wants a look: it failed, it was not accepted, or it carries a flag. Sent in addition to od.completed

client.webhooks.create(url, events=["od.flagged"]) hears only of those.

Receiving them

from lunaspace.webhooks import InvalidSignature, verify


def handle(body: bytes, headers) -> None:  # in your web framework's handler
    try:
        event = verify(secret, body, headers["Luna-Signature"])
    except InvalidSignature:
        return  # refuse it
    if event["event"] == "od.flagged":
        ...
  • Check the signature. The header Luna-Signature: t=<seconds>,v1=<hex> carries the HMAC-SHA256, with your secret, of <seconds>.<body>, the body exactly as received. verify() checks it and that t is recent, and returns the event.

  • Answer with a 2xx status within ten seconds. Otherwise the delivery is sent again after 1, 5 and 30 minutes, then 2, 6 and 24 hours, and then given up. The same delivery keeps its id (also in the header Luna-Delivery): use it to ignore one that arrives twice.

  • The address must be https and public. Redirects are not followed. An organisation has at most five webhooks.