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:
- Email your HTTPS URL to support@hoppier.com.
- We send you the endpoint’s signing secret, which starts with
whsec_. You get it once, so store it in your secrets manager.
- 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:
- Read the raw request body, before any JSON parsing.
- Compute the HMAC-SHA256 of
<t>.<raw body>, as a hex string. The key is your whole signing secret, whsec_ prefix included.
- 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.
- 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.