Webhooks

Webhooks enable Nearby Now to call a script on your server when one or more events have happened. Webhooks can be thought of as event listeners or push notifications.

An event, is an occurrence of a specific action on your account taken by a user or customer, such as a checkin, review requests, or completed customer review.

You might consider webhooks to:

  • Keep a data warehouse updated with tech checkin or customer review information
  • Update a CRM or Sales tool with information about a completed review
  • Trigger a coupon email or marketing campaign to happy customers
  • Use checkin location data and good customer reviews to send neighbors marketing flyers
  • Send internal negative review notifications

Configuring Webhooks

Webhooks are configured in the integration area inside the admin portal. Clicking on the webhooks integration reveals instructions on how to activate webhooks and supply your webhook endpoint URL.

The URL that you supply for your endpoint URL must be a dedicated page on your server coded per our instructions.

Receiving a webhook

Creating a webhook on your server is straightforward and you can accomplish this use most modern programming languages. Webhook data is sent from our servers to your endpoint as JSON in the POST request body. The full event details are included in each webhook notification.

Here is a simple PHP example webhook receiver:

// Retrieve the request's body
$input = @file_get_contents("php://input");
// Parse it as JSON
$event_json = json_decode($input);
// Do something with $event_json ...
// Reply back with an HTTP 200 status code
http_response_code(200);

Responding to a webhook

Your endpoint should return a 200 HTTP status code. Any other information returned in the request headers or request body are ignored. Any HTTP status code that is not 200 will indicate to Nearby Now that you did not receive the webhook successfully and we will treat it as a failure.

Failures are logged and webhooks automatically deactivated if three or more events get discarded.

Available Events

Type Event Name Description
Checkin checkin.created Sends a full checkin object when a checkin had been created
Review review.completed Sends a full review, customer, and checkin object after a customer completes a review
Customer customer.created Sends a full customer, review, and checkin object after a customer completes a review

Headers

Each webhook includes a custom header: X-Account-Key: The Storefront API Key

Verifying

To verify that the webhook is coming from Nearby Now use the X-Account-Key to validate that against your Storefront API Key.

Example Objects

Checkin

{
  "obj": "event",
  "type": "checkin.created",
  "id": "02f55124-0c6b-46aa-a445-5507ebad135b",
  "createdAt": 1466022495,
  "data": {
    "obj": "checkin",
    "id": "a7d5ad8b-d512-4f4b-8dd1-6114de03e212",
    "createdAt": 1466022495,
    "location": {
      "street": "16601 N Pima Rd",
      "city": "Scottsdale",
      "state": "AZ",
      "postalCode": "85260",
      "country": "US",
      "latitude": 33.6430563,
      "longitude": -111.8739084
    },
    "reference": "Example checkin reference",
    "image": "http://some_image_url",
    "user": {
      "name": "Demo User",
      "email": "demo@example.com"
    },
    "source": "api"
  }
}

Review

{
  "obj": "event",
  "type": "review.completed",
  "id": "02f55124-0c6b-46aa-a445-5507ebad135b",
  "createdAt": 1465997370,
  "data": {
    "obj": "review",
    "summary": "Example Review Summary",
    "detail": "Example Review Detail",
    "overallRating": 5,
    "dateRequested": 1465997370,
    "dateResponded": 1465997370,
    "starsImage": "http://some_image_url",
    "customer": {
      "name": "John Q Sample",
      "email": "john@example.com",
      "sms": "5555555555"
    },
    "checkin": {
      "id": "a7d5ad8b-d512-4f4b-8dd1-6114de03e212",
      "createdAt": 25200,
      "location": {
        "street": "16601 N Pima Rd",
        "city": "Scottsdale",
        "state": "AZ",
        "postalCode": "85260",
        "country": "US",
        "latitude": 33.6430563,
        "longitude": -111.8739084
      },
      "reference": "Example checkin reference",
      "image": "http://some_image_url",
      "source": "api",
      "user": {
        "name": "Demo User",
        "email": "demo@example.com"
      }
    }
  }

Customer

{
  "obj": "event",
  "type": "customer.created",
  "id": "02f55124-0c6b-46aa-a445-5507ebad135b",
  "createdAt": 1465997413,
  "data": {
    "obj": "customer",
    "name": "John Q Sample",
    "email": "john@example.com",
    "sms": "5555555555",
    "review": {
      "summary": "Example Review Summary",
      "detail": "Example Review Detail",
      "overallRating": 5,
      "dateRequested": 1465997413,
      "dateResponded": 1465997413,
      "starsImage": "http://some_image_url"
    },
    "checkin": {
      "id": "a7d5ad8b-d512-4f4b-8dd1-6114de03e212",
      "createdAt": 25200,
      "location": {
        "street": "16601 N Pima Rd",
        "city": "Scottsdale",
        "state": "AZ",
        "postalCode": "85260",
        "country": "US",
        "latitude": 33.6430563,
        "longitude": -111.8739084
      },
      "reference": "Example checkin reference",
      "image": "http://some_image_url",
      "source": "api",
      "user": {
        "name": "Demo User",
        "email": "demo@example.com"
      }
    }
  }

Latest Blog Posts

Contact