Skip to main content

Webhook signatures and delivery

This page applies to integration webhooks and to a workspace's general webhook endpoints alike: both are signed and delivered the same way.

The request​

Each delivery is a POST to your URL:

POST /hooks/murmle HTTP/1.1
Content-Type: application/json
X-Pollinator-Signature: t=1791200043,v1=5d41402abc4b2a76b9719d911017c592...
X-Pollinator-Event: submission.completed
X-Pollinator-Delivery: 0b7f1c8e-6d1a-4a8e-9f3e-2a6f4b8c9d01

{"event_id":"0b7f1c8e-...","event_type":"submission.completed","created_at":"...","data":{...}}

X-Pollinator-Delivery equals the event's event_id and is the same on every attempt.

Verifying the signature​

v1 is the lowercase hex HMAC-SHA256, keyed with your signing secret (UTF-8), over the bytes <t> + . + <raw request body>. The timestamp is inside the signed material, so a captured request cannot be replayed later under a fresh timestamp.

  1. Parse t and v1 from the header; reject a malformed header.
  2. Reject if |now - t| is more than your tolerance. Murmle's own reference uses 300 seconds.
  3. Compute the HMAC over the raw body bytes as received - not a re-serialised parse of them.
  4. Compare with a constant-time comparison.
import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
try:
parts = dict(piece.split("=", 1) for piece in header.split(","))
timestamp, provided = int(parts["t"]), parts["v1"]
except (ValueError, KeyError):
return False
if abs(int(time.time()) - timestamp) > tolerance:
return False
expected = hmac.new(
secret.encode("utf-8"), f"{timestamp}.".encode() + body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, provided)

Delivery, retries and idempotency​

  • At least once. Murmle writes an event in the same database transaction as the change it describes, then delivers it from a queue. An event is never sent for a change that rolled back, and is not lost if a server restarts. It can arrive more than once.
  • Deduplicate on event_id. Record the ids you have processed, or make the write itself idempotent - the same outcome applied twice grades once.
  • 2xx means done. Any 2xx within 10 seconds completes delivery to you. Anything else - a 4xx, a 5xx, a timeout, a connection failure - is retried. So return 2xx for events you have deliberately ignored; a non-2xx means "send it again". Murmle does not read your response body.
  • Retries. The queue is worked every 15 seconds. A failed event is retried with an exponentially growing wait (2, 4, 8, 16, 32, 64 and 128 seconds, each rounded up to the next 15-second tick), for 8 attempts in all - roughly five to six minutes from the first attempt to the last. After the eighth failure the event is abandoned. Each attempt carries a fresh signature timestamp.
  • Redelivery can follow someone else's failure. An event is retried as a unit for all of its recipients, so a delivery that succeeded for you may be repeated because another recipient failed. Deduplication makes this harmless.
  • No ordering guarantee. Use created_at and completed_at, not arrival order.
  • Retention. Murmle keeps delivered and abandoned events for 30 days by default (the operator sets this) and then deletes them. Deleting a session also deletes its events, including any still waiting to be delivered. Webhook delivery is not an archive; Murmle's results and exports are.
If your endpoint was down

Because retries end after a few minutes, an outage of your endpoint longer than that loses webhook deliveries. An integration can recover them by pulling outcomes, which reads the same events for the whole retention window.