Vojodevelopers
QuickstartGuidesAPI referenceWebhooks

verification.pod

A Harvester reading was matched to a play

Proof of Display: sent the first time a Harvester reading is matched to a play, meaning the optical sensor on the screen saw the creative's fingerprint. Each endpoint receives this at most once per play, and later readings for that play don't send it again. If you subscribed after a play's first reading, a later reading can still send that play's event. events holds the play's Harvester readings at that moment, usually exactly one.

createdAt on a reading is the time the device reported. Current Harvesters round it down to a 10-minute bucket, so use the play's t0 to place the play in time.

Payload

Fires once, the first time a Harvester reading is matched to a play. events is the play's Harvester events at firing time, in createdAt order — not a derived summary.

  • eventTypestringRequired

    Always verification.pod

  • eventIdstringRequired

    Stable per-event id, constant across retries (injected at delivery). Dedupe on this.

  • playIdstringRequired
  • organisationIdstringRequired
  • t0stringRequired

    Epoch (seconds) the play opened. Prefer this over a reading's createdAt for placing the play in time.

  • eventsarray of objectsRequired
    Show 6 fields
    • typestringRequired

      Always HARVESTER

    • createdAtstringRequired

      Device-reported epoch seconds. Floored to a 10-minute bucket on v1 Harvester firmware.

    • fingerprintstring or nullRequired

      The fingerprint code the Harvester read from the screen.

    • deviceKeystring or nullRequired

      Identifier of the Harvester device that took the reading.

    • matchedAtstring or nullRequired

      Epoch seconds the reading was matched to this play.

    • matchRuleVersionstring or nullRequired

      Version of the matching rule that attached the reading, e.g. play-match@1+cv-fingerprint-match@1.

  • attemptIdstring

    Per-attempt id; CHANGES on each retry. Do not dedupe on this.

  • screenIdstring or null
  • creativeIdstring or null
  • externalPlayIdstring or null

    Your own per-play id, when the player supplied one at playback.

Handling this event

Verify the signature, reply with a 2xx within 20 seconds, then process the event in the background. Retries reuse the same event id, so deduplicate on it.