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 |
|---|---|
|
A run finished, well or not |
|
A finished run that wants a look: it failed, it was not accepted, or it carries a flag. Sent in addition to |
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 thattis 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 headerLuna-Delivery): use it to ignore one that arrives twice.The address must be
httpsand public. Redirects are not followed. An organisation has at most five webhooks.