Skip to main content
Hoppier can send a signed HTTPS POST to your server when something happens in your account. There is one event today: card.claimed.

card.claimed

Hoppier sends card.claimed when it sets a reward aside for a participant:
  • straight away, if the person you added already has a Hoppier account, or
  • when a new person accepts their invite and signs in for the first time.
card.claimed does not mean the person spent anything, opened an email or chose a gift card. Treat it as “Hoppier has set this reward aside for this person”, nothing more.
  • It’s sent for gift-card programs only, for now.
  • data.amount is the program’s amount per person, in dollars. On a program where each person has their own amount, it’s 0.
  • data.card_type_specific.provider and external_id are always null at this point, because the gift-card brand is chosen later.
Every field is described in the card.claimed reference.

Set up an endpoint

During the beta, Hoppier registers endpoints for you:
  1. Email your HTTPS URL to support@hoppier.com.
  2. We send you the endpoint’s signing secret, which starts with whsec_. You get it once, so store it in your secrets manager.
  3. Ask us for a test event. It looks like a real one, with an id that starts with evt_test_ and sample data.
To change the URL, rotate the secret or stop deliveries, email us again.

Verify the signature

Every request carries an X-Hoppier-Signature header:
  1. Read the raw request body, before any JSON parsing.
  2. Compute the HMAC-SHA256 of <t>.<raw body>, as a hex string. The key is your whole signing secret, whsec_ prefix included.
  3. Compare the result, in constant time, with each v1= value in the header. Accept the request if any of them matches. While a secret is being rotated there are two v1= values, one for each secret.
  4. Reject the request if t is more than 300 seconds old. Hoppier signs with the time it sends, so this stops old requests from being replayed.

Retries and duplicates

  • Answer with any 2xx status within 10 seconds. Do slow work after you’ve answered.
  • Anything else (another status, a timeout, a network error) is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. After the last retry Hoppier stops and our team is alerted. Email us if you need an event sent again.
  • The same event can arrive more than once. Ignore any event whose id you’ve already processed.
  • Events can arrive out of order.