How do Kitetags webhooks work?

Each time someone taps a Kitetag that has a webhook interaction configured, the Kitetags platform sends an HTTP POST request to the URL you specified. The request body contains a JSON object with the tag’s identity, metadata, and all KDS (Kitetag Data Structure) field values.

sequenceDiagram
    participant Phone as Smartphone
    participant Tag as Kitetag
    participant Platform as Kitetags Platform
    participant Endpoint as Your Webhook Endpoint

    Phone->>Tag: Tap (NFC read)
    Tag-->>Phone: Tag URL
    Phone->>Platform: Opens tag URL
    Platform->>Endpoint: POST JSON payload
    Endpoint-->>Platform: 200 OK
    Platform-->>Phone: Displays response page

What headers does Kitetags send?

Every webhook request includes these HTTP headers:

Header Value
Content-Type application/json
User-Agent Kitetags-Webhook/1.0
X-Kitetags-Event tag.tapped
X-Kitetags-Delivery A unique UUID for this delivery

What does the webhook JSON payload look like?

Here is an example payload for a tag in an employee badge group with custom KDS fields:

  {
  "event": "tag.tapped",
  "timestamp": "2026-03-27T14:32:08Z",
  "tag": {
    "uid": "04A23CF2B96A80",
    "callsign": "blue-falcon-42",
    "group": {
      "id": "grp_9f8e7d6c",
      "name": "Conference Badges"
    }
  },
  "kds_fields": {
    "first_name": "Jordan",
    "last_name": "Rivera",
    "email": "jordan.rivera@example.com",
    "company": "Acme Corp",
    "role": "Product Manager",
    "ticket_type": "VIP"
  },
  "tapper": {
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 19_0 like Mac OS X)"
  }
}

Payload field reference

Field Type Description
event string Always tag.tapped for tap events
timestamp string ISO 8601 timestamp of the tap
tag.uid string The NFC chip’s unique hardware identifier
tag.callsign string The human-readable callsign assigned to the tag
tag.group.id string The internal ID of the tag’s group
tag.group.name string The display name of the tag’s group
kds_fields object Key-value pairs for every field in the tag’s KDS. Field names match what you defined in the dashboard.
tapper.ip string The IP address of the device that tapped the tag
tapper.user_agent string The browser user-agent string of the tapping device

How should you receive webhooks?

Your endpoint must return an HTTP 200 status code within 10 seconds. If the request times out or returns a non-2xx status, Kitetags retries up to 3 times with exponential backoff.

Tips for building a reliable webhook receiver

  • Respond quickly. Send a 200 OK immediately, then process the data asynchronously. Long-running tasks should be handed off to a background queue.
  • Validate the delivery ID. Use the X-Kitetags-Delivery header to deduplicate retried deliveries.
  • Use HTTPS. Kitetags sends webhook data over HTTPS only. Make sure your endpoint has a valid TLS certificate.

How can you test webhooks without a server?

Use a free tool like webhook.site to get a temporary URL that captures incoming requests:

  1. Go to webhook.site and copy your unique URL.
  2. In the Kitetags dashboard, create a webhook interaction and paste the webhook.site URL as the endpoint.
  3. Tap your Kitetag.
  4. Refresh webhook.site to see the payload.

This is the fastest way to inspect the exact JSON your integration will receive. Once you are satisfied with the payload structure, replace the test URL with your production endpoint.

Next steps

  • Set up a no-code automation with Zapier if you do not want to build your own endpoint
  • See integration examples for patterns like event check-in and product authentication
  • Learn how to configure the Webhooks app in the dashboard

Last updated 27 Mar 2026, 06:51 +0900 . history