Introduction
This document will help you understand how Snap Send Solve webhook integration works and how to configure it to receive report payloads whenever a new report is created in Snap Send Solve.
Overview
Snap Send Solve is a platform that enables users to report issues such as potholes, graffiti and damaged infrastructure directly to local authorities and service providers. Our webhook integration allows your organisation to receive these reports into your systems instantly, facilitating faster response times and more efficient resolution of issues. With our webhook integration, Snap Send Solve pushes a report payload to your specified webhook URL as soon as a report is created, ensuring you have real-time access to the information.
Authentication
To ensure secure communication between Snap Send Solve and your webhook endpoint, we support two types of authentication: OAuth 2 and API Key. This section explains how to configure both methods.
OAuth 2
Obtain an OAuth 2 Token: Snap Send Solve will follow the OAuth 2 flow to obtain an access token from your identity provider.
Include the Token in Requests: This token will be included in the
Authorizationheader of each HTTP request in the format:Bearer OAUTH2_TOKEN. Your endpoint must validate this token to ensure the request is legitimate.
API Key
Provision API Key: The API key provisioned should be exclusively utilized for Snap Send Solve integration only.
Include the API Key in Requests: This API key will be included in the
X-API-KEYheader of each HTTP request in the format:YOUR_API_KEY. Your endpoint must validate this token to ensure the request is legitimate.
Handling Snap Send Solve Request Payload
When a new report is created in Snap Send Solve, the platform sends a HTTP POST request to the configured webhook URL. The payload of this request is in JSON format and contains information about the report.
Request Payload Example:
Your webhook should be configured to handle this payload and process the information accordingly.
{
"id": 4282573,
"images":
[
"https://snapsendsolve-reports.s3.ap-southeast-2.amazonaws.com/images/04282573/public/1_csr7csl16zoa.jpg"
],
"address": "15 Palmer Parade, Cremorne VIC 3121, Australia",
"notes": "test report",
"latitude": "-37.8314644",
"longitude": ", 144.9929973",
"incidentType": "Snap Send Solve - Test",
"date": "2024-02-13T21:48:20.826Z",
"additionalFields":
[
{
"name": "Question 1",
"value": "answer 1"
},
],
"reportUrl": "https://snapsendsolve.page.link/ahxrsas8",
"reporter":
{
"firstName": "Chris",
"lastName": "Cook",
"email": "test@email.com",
"isPrivateEmail": true,
"phone": "+61400123456",
"address": "",
"suburb": "",
"postcode": ""
},
"location":
{
"address":
{
"streetNumber": "15",
"street": "Palmer Parade",
"suburb": "Cremorne",
"city": "City of Yarra",
"state": "Victoria",
"postcode": "3121",
"country": "Australia"
}
}
}
Field description
id: Unique identifier for the report
positive integer
images: URLs of images attached to the report (if any).
array of strings
comments:
can be empty array
the length of each url is up to 2048 characters
address: Address where the issue was reported.
string up to 500 characters
notes: Additional notes provided by the reporter.
string up to 10000 characters
latitude and longitude: Coordinates of the reported location.
string up to 50 characters
incidentType: Type of incident reported.
string up to 100 characters
date: Timestamp of when the report was created.
string, in ISO 8601 datetime format
additionalFields: Additional fields associated with the report (if any).
array of object
name: string up to 100 characters
value: string up to 500 characters
reportUrl: URL to view the report details.
string up to 2048 characters
reporter: Information about the reporter.
firstName: string up to 100 characters
lastName: string up to 100 characters
email: string up to 255 characters
isPrivateEmail
boolean
incident whether this reporter is using apple private relay email
phone: string up to 50 characters
address: string up to 100 characters
suburb: string up to 50 characters
postcode: string up to 50 characters
location: Detailed address information.
streetNumber: string up to 100 characters
street: string up to 100 characters
suburb: string up to 100 characters
city: string up to 100 characters
state: string up to 100 characters
postcode: string up to 100 characters
country: string up to 100 characters
Configuring the Webhook
To configure the Snap Send Solve webhook, please contact your account manager. They will assist you in setting up the webhook integration once you have supplied the following information.
Report creation:
HTTP endpoint that receives POST requests
API Rate limiting details (if applicable)
Based on your preferred authentication methods, please provide the following information:
OAuth 2 Configuration:
Your identity provider's OAuth 2 endpoint (authorisation endpoint)
OAuth 2 client credentials (client ID and client secret) for your application
Any additional OAuth 2 configuration settings required by your identity provider
API Key Configuration:
API key for Snap Send Solve integration system
Error Handling, Retries and Rate Limiting
Snap Send Solve has implemented following mechanism to ensure the reliability and resilience of the integration.
Error Handling:
Handle HTTP status codes returned by the webhook endpoint appropriately. Common status codes include:
2xx : The request was successful.
4xx / 5xx : Client errors or Server errors
Snap Send Solve will retry this request after 15 minutes.
After two consecutive fails, the request will be put to a dead letter queue which will be manually handled by Snap Send Solve’s technical team.
Rate Limiting:
Snap Send Solve imposes rate limits on webhook requests to prevent abuse and ensure fair usage.
It is important to implement rate limiting on your end as well to prevent your system from overwhelming the webhook endpoint with requests.
The default limit is 5 requests per second.
Need more help? Get support from our team by emailing us at contact@snapsendsolve.com or sending us a message.