Outbound Valuation Webhooks: The Opagio Developer Guide

A scheduled pull is the right way to start an integration. It is not the right way to finish one. Once your reporting job is stable, the interesting question stops being how do I get the data and becomes how do I know something changed — because polling a valuation endpoint every fifteen minutes to catch a quarterly event is an expensive way to learn nothing.

Opagio answers that with outbound webhooks: an HTTPS POST from Opagio to a URL you control, sent when a qualifying action happens inside the platform. This guide is the companion to the intangible asset valuation API developer guide, which is a prerequisite — you will need an API key and the write:webhooks scope described there before anything here is actionable.

As with that guide, every claim below is verified against the shipped delivery code rather than a roadmap. Where a property does not exist, this guide says so plainly, because a webhook integration built on an assumed guarantee fails silently and at the worst possible moment.

The delivery contract at a glance

Two design decisions sit behind the rest of this guide. First, dispatch is fire-and-forget: the platform action that triggers an event does not wait for your endpoint to answer, so a slow or broken receiver never blocks a user's request inside Opagio. Second, delivery is per-subscription and parallel, which means there is no ordering guarantee between subscriptions, and none between events either.

Step 1 — Register a subscription

Subscriptions are created through the Public API with a key holding the write:webhooks scope:

curl -s -X POST https://opag.io/api/v1/webhooks \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/opagio","events":["report.generated"]}'

The URL must begin with https:// — plain HTTP is rejected with a 400 and HTTPS URL is required. At least one event name is required. The submitted list is then filtered against the catalogue, and only recognised names are stored; if none survive the filter, the request fails with a 400 that names every valid event in the message.

That filtering is quiet rather than loud. Submit five event names of which two are misspelled, and you get a 201 with three events, not an error. The 201 response body echoes the events array that was actually stored, so compare it against what you sent rather than assuming your request was honoured verbatim.

Subscriptions can also be managed inside the platform, under Settings → Webhooks, by a user with the SETTINGS_UPDATE permission. Both paths write the same underlying records, so a subscription created in the interface is visible and editable through the API and vice versa.

Step 2 — Verify the signature on every delivery

Each delivery carries a hex-encoded HMAC-SHA256 of the raw request body, keyed with your subscription secret, in the X-Opagio-Signature header. Recompute it and compare.

const crypto = require('crypto');

function verify(rawBody, headerSignature, secret) {
  const expected = crypto.createHmac('sha256', secret)
    .update(rawBody)          // exact bytes as received
    .digest('hex');
  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(headerSignature || '', 'utf8');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Two failure modes account for most broken verifications. The first is parsing the body before hashing it: a framework that runs a JSON body-parser ahead of your handler leaves you re-serialising an object, and the re-serialised bytes will not match the bytes that were signed. Capture the raw body. The second is a non-constant-time string comparison, which leaks timing information; use timingSafeEqual or your language's equivalent.

What the signature does and does not prove

There is no delivery-ID header and no separate signed timestamp header. The envelope does carry an ISO 8601 timestamp field inside the signed body, so you can reject deliveries older than a window you choose — and because that field is inside the signed payload, it cannot be altered without invalidating the signature. That is the replay control available to you today. Build your own idempotency on top of the payload's own identifiers, such as reportId or companyId, rather than on a header Opagio does not send.

Step 3 — Know which events actually fire

The catalogue holds 26 subscribable event names. Only nine have an emitter wired behind them today. A subscription to any of the other seventeen is accepted, stored, and will never fire.

The nine events that fire today

Note that portfolio.company.updated never sends the changed values — only the names of the fields that changed. If you need the new values, treat the event as a signal and fetch the record from GET /portfolio/companies/:id.

The remaining seventeen names — every valuation.* event, portfolio.updated, company.added, company.updated, portfolio.imported, the intelligence.* family, the rest of prediction.*, the automation.* family and benchmark.dynamic.computed — are declared for future use. They are placeholders, not capabilities, and should not appear in an integration you are relying on.

Step 4 — Handle the payload envelope

Every delivery uses the same three-field envelope, regardless of event:

{
  "event": "report.generated",
  "timestamp": "2026-09-03T10:00:00.000Z",
  "data": { "reportId": "…", "type": "…", "title": "…" }
}

The event name appears in both the header and the body. Route on either, but verify the signature before you trust either — the header is not signed independently of the body, so a receiver that dispatches on X-Opagio-Event before verification is acting on unauthenticated input.

Only subscriptions that are active and whose stored events array includes the event name receive a delivery. Everything else is filtered out before any HTTP request is made.

Step 5 — Design for the failure behaviour

This is the section that determines whether your integration is reliable, because the failure model is stricter than most webhook implementations developers will have met.

Because the counter resets on success, the ten failures must be consecutive. An endpoint that fails intermittently will stay enabled indefinitely and quietly lose the events it missed. An endpoint that goes down for a sustained period will be disabled and will then miss everything until someone re-enables it — nothing re-enables it automatically.

That last sentence is the whole argument for the integration pattern recommended at the end of this guide. Webhooks tell you when; a periodic read tells you what is true. An integration with only the first has no way to heal itself.

Every attempt is written to a delivery log that records the event, the payload, the HTTP status your endpoint returned, and the first 1,000 characters of your response body. That truncated body is genuinely useful when diagnosing a failing receiver — and it is a reason to keep error responses free of anything you would not want stored, since your response is retained on the Opagio side as part of the delivery audit trail.

Step 6 — Manage subscriptions over their lifetime

The list endpoint returns your organisation's subscriptions newest first, with the secret removed from every record. A subscription belonging to a different organisation returns 404 rather than 403 on update or delete, consistent with the rest of the API: another tenant's resource is reported as absent, never as forbidden.

PUT /webhooks/:id accepts url, events and active, each optional. Sending {"active": true} is how you re-enable a subscription that auto-disabled. A url supplied here is held to the same HTTPS requirement as at creation.

Ivan Gowan — CEO, Co-Founder

25 years as tech entrepreneur, exited Angel

Connect on LinkedIn →