Collection Webhooks

Collections webhooks provide organizations with the ability to receive trigger-based updates when new assets are added to or removed from their Collection. Webhooks deliver Censys data to various applications, enabling users to monitor events and take action as needed.

Webhooks enable scalability by delivering critical updates without the need to make frequent API calls. Subscribing to events for new assets returned by a query eliminates pagination and delta calculations.

Webhook events for new infrastructure

Track new hosts, web services, and certificates that match a query using two new events:

Asset Added to collection
Asset Removed from Collection

Requirements

Only the Administrator of your Censys Organization can configure webhooks.
Free tier cannot create webhooks, Starter and Enterprise tiers can.
You must create a Collection to use webhooks. For more information, see Collections.

Target URL

Every webhook requires a target URL, which is the destination of the webhook payload. The target URL is typically generated by the system or application that receives and processes the webhook events — Slack for example.

To obtain a target URL, set up a service or app that can receive HTTP POST requests. Most platforms provide this URL during configuration. Store the URL in a secure place, as anyone with access to it can trigger the workflow.

Once you have the target URL, add it to your Censys webhook configuration in the steps below.

Create a webhook

Follow the instructions below to create a webhook:

Go to Settings in the side navigation menu.
Click Alerts and Notifications.
On the Alerts and Notifications page, click Create New Webhook.
Name your webhook.
Enter the target URL. This URL is where Censys sends HTTPS requests for event delivery. The target URL is provided by the web service that receives the events.
Select one or more collections as the source of trigger events.
(Optional) Add custom headers to the webhook configuration as part of the request. Custom headers are used for authentication or to route requests.
In the Event Types section, select the checkbox for each collection event you want to trigger the webhook.
In the Advanced Settings section, Select an optional payload template. The payload template defines the structure and content of the data sent to your webhook URL when a collection event occurs.
Click Test Webhook.

Test a webhook

When you click Test Webhook at the end of the configuration process, a message is sent to the target URL. You should receive a message in the destination application, Slack for instance.

In the UI, the Headers and Request Body of the request are displayed under the Request tab. The Response tab provides you with an HTTP response code, the response headers and body.

Headers & Request Body

The Request tab allows you to review request headers and request body.

Headers

View the request headers.

Content-Type	application/json

Request Body

The example below is the request body from a webhook. "asset_type": "cert" and "event_type": "add" alert the user that a new certificate has been added for Vandelay Industries. The query field contains the original query in the collection: "query": "cert.parsed.subject.organization: "Vandelay Industries"".

{
  "asset_id": "f9f055ac237c123b9a7a8644832319ad41d399c9f714f52bc6a02c4a875cfb27",
  "asset_type": "cert",
  "collection_id": "364133a0-53ae-4f51-82d0-17c25aed92e3",
  "collection_name": "Certificates belonging to Vandelay Industries",
  "event_type": "add",
  "evidence": "cert f9f055ac237c123b9a7a8644832319ad41d399c9f714f52bc6a02c4a875cfb27 was added to collection 364133a0-53ae-4f51-82d0-17c25aed92e3 on 2025-02-03T20:03:01Z based on the collection query.",
  "org_id": "00000000-0000-0000-0000-000000000000",
  "query": "cert.parsed.subject.organization: "Vandelay Industries"",
  "timestamp": "2025-02-03T20:03:01Z",
  "url": "https://platform.censys.io/collections/364133a0-53ae-4f51-82d0-17c25aed92e3?org=00000000-0000-0000-0000-000000000000"
}

Response

The Response tab displays the HTTP response code indicating success or failure, along with the response Header and Body.

Troubleshoot errors by checking the response body for details, especially if you receive a 400 Bad Request. Common errors include:

Incorrect URL: Verify that the destination URL is correct and accessible from the internet.
Authentication Problems: If your webhook requires authentication, verify your credential configuration.
Firewall Restrictions: Verify that your firewall is not blocking requests from Censys.

View recent webhook deliveries

Censys records and stores delivery history for the past 14 days. To view the delivery history for a webhook:

Go to Manage Webhooks.
Click the menu option to the right of the Webhook Name to view recent deliveries.
Expand the row to see details about the delivery.

Edit or delete webhooks

After you create a webhook, you can edit, or delete the webhook at any time.

Edit webhooks

Go to Manage Webhooks.
Click the webhook name.
Edit webhook settings as needed.
Click Save Webhook.

Delete webhooks

When you delete a webhook, it cannot be restored.

Go to Manage Webhooks.
Click the menu option to the right of the Webhook Name and select the remove icon.
Verify the action by clicking Confirm.