Skip to main content

Webhooks for Snapshot

Our service supports webhooks. It allows you to receive an HTTP POST request to a target URL of your choosing.

  • A webhook is sent for each call to the recognition API, even when no license plate is found.
  • The target_url should return a valid HTTP status code (200). If the target_url consistently returns an error code, the hook will be removed and an email will be sent to the account owner.
  • To quickly test out this feature, you can use a service like webhook.site. It generates a unique target URL and displays all the requests made to that URL.

Webhook Types​

There are two types of webhooks you can configure: "Data Only" and "Webhook with Image".

Data Only Webhook​

This webhook sends a POST request to your target_url with a JSON payload in the request body.

Request Header:

Content-Type: application/json

Webhook With Image​

This webhook sends a POST request to your target_url with a multipart/form-data content type. Receiving this data is like receiving the content of a form with an input of type file.

Request Header:

Content-Type: multipart/form-data

The request body has two fields:

  • json: The JSON encoded data containing all detection results and metadata.
  • upload: The image binary content as a file (image/jpeg format).

Payload Structure​

Example of POST payload:

{
  "hook": {
    "target": "https://webhook.site/dd8ddd2e-ada9-4a4d-b249-66fcb2615848",
    "id": 479,
    "event": "image.done"
  },
  "data": {
    "filename": "car2.jpg",
    "timestamp": "2025-09-09 23:22:38.030345",
    "camera_id": null,
    "results": [
      {
        "box": {
          "xmin": 586,
          "ymin": 656,
          "xmax": 827,
          "ymax": 708
        },
        "plate": "fm046sc",
        "region": {
          "code": "fr",
          "score": 0.655
        },
        "score": 0.999,
        "candidates": [
          {
            "score": 0.999,
            "plate": "fm046sc"
          },
          {
            "score": 0.863,
            "plate": "fmo46sc"
          }
        ],
        "dscore": 0.876,
        "vehicle": {
          "score": 0.968,
          "type": "Sedan",
          "box": {
            "xmin": 260,
            "ymin": 288,
            "xmax": 1205,
            "ymax": 939
          }
        },
        // Make Model, Orientation and Color are only available if you set mmc=true
        "model_make": [
          {
            "make": "Generic",
            "model": "Unknown",
            "score": 0.036
          }
        ],
        "color": [
          {
            "color": "blue",
            "score": 0.899
          },
          {
            "color": "white",
            "score": 0.014
          },
          {
            "color": "silver",
            "score": 0.014
          }
        ],
        "orientation": [
          {
            "orientation": "Rear",
            "score": 0.878
          },
          {
            "orientation": "Front",
            "score": 0.07
          },
          {
            "orientation": "Unknown",
            "score": 0.052
          }
        ],
        // Direction is only available if you set mmc=true and direction=true
        "direction": 87,
        "direction_score": 1.0
      }
    ],
    "usage": {
      "calls": 4,
      "max_calls": 25000
    },
    "processing_time": 29.83
  }
}
note

The payload structure can be modified based on your detection_mode parameter configuration. For detailed information about different payload structures for each detection mode, and payload Attributes see the API Reference Response section.

Implementing Your Webhook Receiver​

To create your own webhook receiver, you need to handle different content types based on your webhook configuration:

Processing Data Only Webhooks​

When receiving a "Data Only" webhook, you'll receive a simple JSON payload with Content-Type: application/json.

Key Points for Data Only Implementation:

  • Content-Type will be application/json
  • The request body contains the complete JSON payload with detection results and metadata
  • No image file is included

Processing Webhook With Image​

When receiving a webhook with image, you'll need to parse the multipart form data with Content-Type: multipart/form-data.

Key Points for Image Webhook Implementation:

  • The json field contains all the detection results and metadata
  • The upload field contains the original image file (JPEG format)
  • Content-Type will be multipart/form-data

Receiving Webhook Data​

Not sure how to receive the webhook messages? You can use and modify our webhook receiver (available in multiple languages).

tip

To test if the target is working correctly, you can use a simple curl command to simulate a webhook call. For a "Data Only" webhook:

curl -X POST -H "Content-Type: application/json" -d '{"hook":{"target":"YOUR_TARGET_URL","id":1,"event":"image.done"},"data":{"results":[]}}' YOUR_TARGET_URL

For a "Webhook with Image", you would need to construct a multipart form data request.

On-Premise vs Cloud​

The webhook functionality is available for both Snapshot Cloud and the Snapshot On-Premise SDK.

curl http://localhost:8080/info/
{
  "version": "1.3.8",
  "license_key": "XXX",
  "total_calls": 2500,
  "usage": { "calls": 10 },
  "webhooks": [
    // Your configured webhooks will appear here
  ]
}
info

For the Snapshot On-Premise version, any changes made to the webhook configurations require the Docker container to be restarted to take effect.

Floating button icon
CTRL + .