Request flows

Four flows cover most of what the product does. Each list follows one request from the caller to the database and back, and names the checks made on the way.

A banner loads#

1. The page loads the runtime from /sdk/v1/loader.js, or from a pinned build. The runtime starts and holds back the tags you marked and the third-party tags it recognises.
2. The runtime calls GET /sdk/v1/form with the publishable key. The API checks the key and compares the request's origin with the key's allowed origins.
3. The API settles the property. A key tied to a property reaches only that one. Otherwise a property named in the request is used, and failing that the origin decides.
4. The API works out the visitor's country and subdivision. It reads a country header set by your CDN, or looks the address up in its own database.
5. The property's region rules are matched. The most specific place wins: subdivision, then country, then continent, then the fallback.
6. The rule names a form, and its current published version is returned. The answer also carries the visitor's recorded choice, if there is one, and says whether to ask again.
7. The runtime shows the notice and reports the view. Views are stored as daily counts without identifiers.

A request can name a form itself, and the region rules then do not choose the form. A form key that does not exist fails closed: no banner is shown and nothing new is allowed.

A choice is saved#

1. The runtime applies the choice in the browser and releases the allowed tags. It sends POST /sdk/v1/consent with the publishable key. Your server makes the same call with a secret key.
2. The API checks the key, its origin or scope, and the rate limits.
3. A repeat with the same Idempotency-Key and body gets the stored response. Otherwise the body is validated. A browser that names an email address, phone number or user id must send an identity proof.
4. A database transaction starts. A lock for this person and form stops two first answers from creating two records.
5. The record is found or created by the keyed hash of the identifier. It takes the form version shown, the decisions, the country and the law.
6. The new state is sealed as an event and chained to the one before. The transaction commits.
7. A consent.granted or consent.updated webhook is queued.
8. After the UTC day closes, the event becomes a leaf of that day's anchor.

Consent can only be recorded against a published form. Every purpose that can be declined must be answered, and nothing else.

A webhook is sent#

1. An event happens. The API writes one outbox row for each enabled endpoint that subscribes to that event type.
2. The outbox is read at once, and then every 15 seconds. One replica sends up to 50 due events in a run.
3. The endpoint's address is resolved. An address on a private, loopback or link-local network is refused, and the check is repeated when the connection is made.
4. The body is signed with the endpoint's secret and posted. X-Piedap-Signature carries an HMAC-SHA256 of the timestamp and the raw body.
5. An answer of 2xx within eight seconds counts as delivered. Anything else, including a redirect, counts as failed.
6. A failed event is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours. After seven attempts it is marked FAILED.
7. Ten events in a row that fail this way switch the endpoint off. Delivery logs and settled events are deleted after 30 days.

The outbox row is written after the record's transaction commits, in a separate write. If that write fails, the failure is logged and the record stays. Every retry carries the same event id, so your receiver can drop duplicates.

A person is erased#

1. Erasure starts from a rights request, from Records in the console, or from your server. The server call is POST /sdk/v1/subjects/erase and needs the subjects:erase scope.
2. The identifier is hashed. Every record that matches it directly, or through a linked identifier, is found and locked in one transaction.
3. The person's email confirmation entries and linked identifiers are deleted.
4. Each consent still in force gets a WITHDRAWN event first. Every optional purpose becomes refused.
5. The identifying details are removed from each record. These are the readable identifier, the fingerprint, the IP address hash, the browser, the page address and your metadata.
6. An ERASED event is sealed for each record, and the transaction commits.
7. consent.withdrawn is queued for each consent that was in force, and subject.erased for each record. Both carry the fingerprint as it was before the erasure.
8. Your systems erase their own copy when the webhook arrives.

Related#

• Components
• How consent is proven
• Receive webhooks
• Withdraw or erase a person