Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see Get started.
Reopening is intentionally not an event: it permits future work but is not a review/input/terminal outcome. Poll current Task details when you need all intermediate transitions. A delivery payload is a historical snapshot, not a promise that the Task remains in that state when your receiver processes it.
Webhooks notify external receivers. To resume a Melso-managed Task or chat agent after another accessible Task changes, use
tasks_watch. Task watches also support opt-in linked PR check events; these do not add event types to the webhook API.
Payload
id, workspace_id, task_id are UUID strings; type, task_identifier, task_status are strings; created_at is a timestamp. run_id and run_status can be null when a Task closes without a Run. task_status follows normal Task precedence, so a pending ask can carry working while its Run exits. Payloads omit prompt text, answers and secrets; fetch details using the Task and interaction APIs.
Signing and delivery
Each POST carriesContent-Type: application/json, Melso-Event-ID, and Melso-Signature: t=UNIX_SECONDS,v1=HEX_DIGEST. Compute HMAC-SHA256 using the literal secret string over timestamp + "." + raw_request_body. Compare signatures in constant time, enforce a timestamp tolerance (for example five minutes), then de-duplicate by event id. Do not parse/re-serialize JSON before verification. Every delivery attempt, including an automatic retry or manual resend, is signed using its attempt timestamp and the current secret. Event IDs and payloads stay fixed. Attempts in the same second can have the same signature when the secret is unchanged.
The company secret is shared by registered endpoints and per-task callbacks. First endpoint creation initializes it and reveals it once. Subsequent creates omit signing_secret. Rotation returns a new secret once and immediately replaces the key for future attempts, including retries; an already in-flight request can still use the old key. Coordinate receiver rotation accordingly.
State changes write payloads and recipients transactionally to an outbox; a separate worker POSTs them. A 2xx acknowledges delivery. Every other status, redirect, network error or timeout retries with exponential backoff (30 seconds, doubling to one hour, plus 0–25% jitter) until the 24-hour window expires. Workers recover expired one-minute leases. Delivery is at least once within this window, with possible duplicates and no ordering guarantee; permanently unavailable receivers end in failed. Resend opens another 24-hour window with the same event ID and cumulative attempt count.
HTTPS is required in all environments. Registration and the connection dialer reject private, loopback, link-local, metadata and reserved addresses, including mixed public/private DNS answers. Delivery pins the validated address, disables proxies/redirects and limits requests to 15 seconds. The log stores at most 4 KiB of UTF-8 response text. Removing/disabling an endpoint suppresses queued future attempts, but cannot recall an in-flight request. Endpoint edits affect future events; queued deliveries retain their original URL. Task callbacks receive all five events and are independent of endpoint subscriptions.
Webhook management routes require a human company owner/admin using a personal token or browser session. Company keys with either tasks or admin scope, Run tokens and MCP actors are denied; see the credential matrix. Recent deliveries return at most 100 rows, newest first. The log keeps cumulative attempts and the most recent response/status, not a separate row for each network attempt.
Connect a receiver
Use an HTTPS receiver you control. Register its public URL through the Webhooks reference, store the returned signing secret securely, and verify requests with the inline functions below. Persist the event and enqueue its work before acknowledging delivery.Verify a signature
Pass the exact raw body bytes, theMelso-Signature header and the literal signing secret. The functions accept a five-minute clock tolerance and reject timestamps too far in the past or future. Keep your receiver clock synchronized.
Deterministic test vector
Use this public test secret only for the example:whsec_documentation_test_only. The exact UTF-8 body below has no trailing newline. It is a minimal signature fixture, not a complete event payload.
1800000000, the expected Melso-Signature header is:
now to the signed timestamp so this test remains repeatable. Production receivers must use the actual current time.
Signature vector passed. After verification in your receiver, parse the payload and persist its event ID with the work you need to do before acknowledging. Use a durable inbox with a unique event ID so repeated deliveries do not repeat your business action. A separate worker can process saved events and record completion.