Webhooks

A webhook is an address on your server. When something happens, Jounce sends a short message there. Your code hears about it at once, without asking over and over. Your developer sets one up through the API with a full access key and picks the events it should hear about. The docs describe the message Jounce sends.

The events

Event	When Jounce sends it
Subscriber created	Someone joined from a form, by hand, or through the API. A CSV import sends List imported instead
Subscriber updated	Their name or custom fields changed, or Jounce found their domain can’t receive mail, or can again
Subscriber subscribed	Someone already on your list became Subscribed, such as by clicking your confirmation link or coming back after unsubscribing
Subscriber unsubscribed	They opted out, so your other tools can follow
Subscriber bounced	Their mailbox rejected an email
Subscriber complained	They marked an email as spam
Added to a segment	They joined a segment, including one set when they were added
Removed from a segment	They left a segment
List imported	A CSV import finished, as one summary with its counts

A CSV import sends that one summary, never one message per row. When your team deletes a custom field, Jounce sends no message for the values it clears. What each status means is in Subscriber statuses.

Who made the change

Every message also carries two fields: who made the change, in one of four words, and the exact way it came in. The docs list every way.

Word	Who
public	Whoever fills in one of your forms. Anyone can type in any address, so it may not be the person
contact	The subscriber, through an email you sent: a link action, an unsubscribe, or a spam complaint
account	You or your team, a CSV import, an API key, or a connected app
system	Jounce, for a bounce or a domain check, or one of your automations, which a sign-up may have started

These fields let your developer hold back a form change before it overwrites what your other tools know. Your developer should still pass on every unsubscribe, bounce, and spam complaint, whoever made it. Both fields are empty when Jounce has no record of who made the change.

Each message about a subscriber includes their name and custom fields, not just what changed. A value typed into one of your forms keeps showing up in later messages, even ones about changes someone else made.

Because a form’s values keep showing up, each message also lists the subscriber’s unverified fields. Those are the names and custom fields one of your forms filled in that no one has changed since. A field leaves the list once anyone changes it.

Your developer can use unverified fields to fill a blank in your other tools, but never to replace what’s there.

How a delivery works

• Signed. Every message has a signature, made with a secret. Jounce shows that secret once, when the webhook is created. Your code checks the signature to be sure the message came from Jounce; the docs show how.
• Retried. If your server doesn’t answer, or answers with anything but a success, Jounce tries again for about six hours, waiting longer each time. An answer of 410 switches the webhook off right away. So do ten deliveries in a row that fail every try.
• Safe to receive twice. Now and then a message arrives more than once. Every copy carries the same ID, so your code can skip the repeat.
• Switched off after a streak. After ten messages in a row fail, even after their retries, Jounce stops sending to that webhook. If your server says the address is gone, Jounce stops at once. Your developer turns it back on through the API once the server is fixed.

Where webhooks live

Your developer creates, lists, and removes webhooks through the API. The Developer API page shows keys only. The key that creates a webhook must be full access; see Full access and read-only keys.

A connected app like Zapier sets up its own webhooks, through its connection rather than a key. Jounce deletes them when that connection ends:

• An Admin or a Manager disconnects the app; see Disconnect a connected app.
• The person who connected it leaves the workspace, is removed, or becomes an Editor.

A webhook made with an API key belongs to the workspace. It stays when someone revokes the key or the person who made it leaves.