Add a webhook trigger source

A webhook source lets your own system tell Aptiro what it knows about an account, on every scan, instead of Aptiro only reading the public web. It is a Scale-plan feature, built for a team with its own product usage data, CRM of record, or support system worth scanning alongside public signals. Up to five endpoints are allowed per organisation.

Adding one

In Settings > Signals > Sources, add a webhook source and point it at your own https endpoint. You will be shown the data terms once, covering what Aptiro sends you, what it does with your response, and that requests are signed so you can verify they came from Aptiro; accepting them is required before the endpoint can be enabled. A signing secret is shown once, you can create a new one at any time, and the old one stops working the moment you do. Test sends a sample request immediately, using an example account or one you choose, so you can confirm your endpoint responds correctly before relying on it in a real scan.

You can also choose up to ten of your own custom fields to share with your endpoint, when your system needs more than an account's name and website to look the account up on its side.

The contract your endpoint implements

On every scan, Aptiro sends a signed POST request as JSON: an event name (account.scan, or test when you press Test), a request id, the account's id, name, website and whichever shared custom fields have a value, and a since timestamp so you only need to return what changed after it.

Verify the X-Aptiro-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body">, keyed with your signing secret) in constant time, and reject anything timestamped more than five minutes away, before trusting the request.

Respond 200 with a documents array, each with a title, an http(s) url (shown as the evidence link on any trigger it produces), a publishedDate, and the text Aptiro's AI reads to find trigger events. Up to 20 documents are read; an empty array is a normal "nothing new" response. A document that does not fit this shape is skipped rather than failing the whole response.

Your endpoint has 10 seconds and 256 KB to respond. 401 or 403 is treated as a rejected credential, 429 as rate limiting, and a timeout or 5xx as unavailable; in every case the scan refunds the credits that endpoint would have cost and still reads your other sources. The full request and response shapes, with worked examples, are kept alongside the code at docs/trigger-sources/WEBHOOKS.md in the mrcrm repository, for whoever on your side is implementing this.

See also: connecting your first data source for the built-in sources that need no integration work at all.