Using the Submission API
This document describes how to submit URLs that you suspect are unsafe to Safe Browsing for analysis, and asynchronously check the results of these submissions. Any URLs that are confirmed to violate the Safe Browsing Policies are added to the Safe Browsing service.
Before you begin
Contact sales or your customer engineer in order to obtain access to this feature.
Best Practices
Read the Safe Browsing Policies
The Web Risk Submission API validates that the submitted URLs render content violating Safe Browsing policies. API developers must ensure that the submitted URLs have clear evidence of violating these policies. The following examples show evidences of violation of policies:
- Social engineering content that mimics system alerts, uses deceptive URLs, or contains fake login pages to phish credentials.
- A site that is hosting a known Malware executable.
Only URLs confirmed to violate these policies are added to Safe Browsing blocklists.
Submit URLs
To submit a URL, send an HTTP POST
request to
the projects.uris.submit
method.
- The Submission API supports one URL per request. To check multiple URLs, you need to send a separate request for each URL.
The URL must be valid but it doesn't need to be canonicalized. For more information, see RFC 2396.
The HTTP
POST
response returns along-running operation
. For more information about how to retrieve the submission result and check the status of a submission, see Long-running operations.
Example
HTTP method and URL:
POST https://webrisk.googleapis.com/v1/projects/project-id/uris:submit
Request JSON body:
{ "submission": { "uri": "https://www.phishingsite.com/" } }
To send your request, choose one of these options:
curl
Save the request body in a file called request.json
,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://webrisk.googleapis.com/v1/projects/project-id/uris:submit"
PowerShell
Save the request body in a file called request.json
,
and execute the following command:
$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://webrisk.googleapis.com/v1/projects/project-id/uris:submit" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/project-id/operations/operation-id", }
Java
Python
Check the submission status
You can check the status of the submission
by using the project-id
and operation-id
values from the response.
SUCCEEDED
indicates that the submitted URL was added to the Safe Browsing
Blocklist.
CLOSED
indicates that the submitted URL was not detected to violate the Safe
Browsing Policies and was not added to the Safe Browsing Blocklist in the last
24 hours.