For pharmacies: get a webhook when a shipment needs FDA personal-import answers, read what is open, and submit everything in one call. Samples use example names and contact details.
When this starts. You can register and test your webhook today, so you are ready for January 20, 2027, when Type 13 entries are required. Zonos uses webhooks to obtain this information when making Type 13 entries. We are also testing this flow with a few shippers. If you would like to take part, contact support@zonos.com or your Zonos rep.
When one of your shipments needs per-shipment compliance answers, Zonos sends your server a webhook with a session ID. You read that session once and submit every answer in one call.
Register. Create a COMPLIANCE_COLLECT_REQUEST webhook once per environment.
Receive. Zonos posts {eventType, sessionId} to your URL.
Read. Query the session for its lines and open questions.
Submit. Send all answers in one questionnaireAnswersSubmit per line.
Before you go live
All requests go to https://api.zonos.com/graphql with your credential in the credentialToken header.
Your credential needs WEBHOOK_WRITE (register and test), COMPLIANCE_READ (read sessions) and COMPLIANCE_WRITE (submit answers).
Answer each product's catalog questions once (drug name, manufacturer). Then shipment sessions only ask the short per-shipment questions in this guide.
Webhooks belong to a mode. Register your production URL with your LIVE credential and a staging URL with your TEST credential.
Do this once with your LIVE credential and once with your TEST credential. Store the returned secret on your server: it signs every delivery. Zonos generates it, and it cannot be set or rotated. If you lose it, read it again with webhook(id: "<id>") { secret }.
Request
POST https://api.zonos.com/graphql
Content-Type: application/json
credentialToken: <your LIVE or TEST credential>
mutation {
webhookCreate(input: {
type: COMPLIANCE_COLLECT_REQUEST
status: ENABLED
url: "https://pharmacy.example.com/zonos/compliance"
}) {
id
type
status
url
mode
secret
}
}
Always COMPLIANCE_COLLECT_REQUEST for this webhook.
sessionId
ID
Map to your order. Pass it to the session query in step 3.
zonos-signature
Header
timestamp=<ms>,hmac=<base64>. Verify the hmac before trusting the body.
checksum
Header
A separate hex HMAC keyed with your API credential, not the webhook secret. You can ignore it once you verify zonos-signature.
Verify the signature
Take the hmac value from the zonos-signature header.
Compute HMAC-SHA256 of the raw request body bytes, keyed with your webhook secret, and Base64-encode it.
Compare the two in constant time. If they differ, respond 401 and do nothing else.
Hash the body exactly as it arrived. Parsing the JSON and re-serializing it changes the bytes, and the hash will not match. The timestamp is the send time in milliseconds but is not part of the signed data, so do not rely on it to block replays.
Verify the signature (Node.js / Express)
import crypto from"node:crypto";
import express from"express";
const app = express();
// express.raw keeps the body as the exact bytes Zonos signed.
app.post("/zonos/compliance", express.raw({ type: "application/json" }), (req, res) => {
if (!isFromZonos(req.body, req.get("zonos-signature"), process.env.ZONOS_WEBHOOK_SECRET)) {
return res.sendStatus(401);
}
res.sendStatus(200);
const { sessionId } = JSON.parse(req.body);
// Queue sessionId for steps 3 and 4.
});
functionisFromZonos(rawBody, signatureHeader = "", webhookSecret) {
// signatureHeader looks like "timestamp=1791327122874,hmac=G/yrP1..."const received = signatureHeader.split(",").find(part => part.startsWith("hmac="))?.slice(5) ?? "";
const expected = crypto.createHmac("sha256", webhookSecret).update(rawBody).digest("base64");
// timingSafeEqual throws on unequal lengths, so check length first.return received.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}
One query tells you what is open. Each line is one program (such as US_FDA) for one item, and you answer each line separately.
Request
POST https://api.zonos.com/graphql
Content-Type: application/json
credentialToken: <your credential>
query ReadSession($id: ID!) {
questionnaireSession(id: $id) {
status
containerType
containerId
lines {
id
status
targetType
answerScopes
program { name }
currentQuestion { code answerType answerScope prompt }
visibleQuestions(requirements: [REQUIRED]) {
question { code answerType answerScope requirement prompt options { value label } }
answer { value }
}
}
}
}
{ "id": "questionnaire_session_0rv8xh6y3xpbm" }
Response: prescription drug, US resident
{"data":{"questionnaireSession":{"status":"IN_PROGRESS","containerType":"CONSIGNMENT","containerId":"consignment_0rv8xh4vhdsem","lines":[{"id":"questionnaire_session_line_0rv8xh6ybxpby","status":"IN_PROGRESS","targetType":"ITEM","answerScopes":["ITEM"],"program":{"name":"US_FDA"},"currentQuestion":{"code":"fda_pip_treatment_basis","answerType":"SINGLE_SELECT","answerScope":"ITEM","prompt":"Who is looking after this treatment?"},"visibleQuestions":[{"question":{"code":"fda_recipient_us_person","answerType":"BOOLEAN","answerScope":"ITEM","requirement":"REQUIRED","prompt":"Is the person receiving this medication a US citizen or permanent resident?","options":[]},"answer":{"value":"true"}},{"question":{"code":"fda_pip_treatment_basis","answerType":"SINGLE_SELECT","answerScope":"ITEM","requirement":"REQUIRED","prompt":"Who is looking after this treatment?","options":[{"value":"US_PHYSICIAN","label":"A doctor licensed in the United States"},{"value":"BEGUN_ABROAD","label":"No US doctor — this continues a treatment started in another country"}]},"answer":null},{"question":{"code":"fda_recipient_name","answerType":"TEXT","answerScope":"ITEM","requirement":"REQUIRED","prompt":"What is the full name of the person making this certification?","options":[]},"answer":null},{"question":{"code":"fda_recipient_phone","answerType":"TEXT","answerScope":"ITEM","requirement":"REQUIRED","prompt":"What is the certifier's phone number?","options":[]},"answer":null},{"question":{"code":"fda_recipient_email","answerType":"TEXT","answerScope":"ITEM","requirement":"REQUIRED","prompt":"What is the certifier's email address?","options":[]},"answer":null},{"question":{"code":"fda_pip_resident_attest","answerType":"CHECKBOX","answerScope":"ITEM","requirement":"REQUIRED","prompt":"I attest that the following is true and correct to the best of my knowledge and belief: …","options":[]},"answer":null}]}]}}}
Already answered (often by Zonos). You can still send your own value.
Follow-up questions are not listed until they apply. The physician name and address only become visible after fda_pip_treatment_basis is US_PHYSICIAN. Send them anyway in the same call. Zonos accepts answers to follow-ups that your own answers unlock.
If a line is still IN_PROGRESS, this names the next missing question.
Encoding value
answerType↕
Encoding↕
Example↕
BOOLEAN
true or false, unquoted
"true"
CHECKBOX
true when ticked, unquoted
"true"
TEXT
A JSON string: the text wrapped in quotes
"\"Jane Doe\""
SINGLE_SELECT
A JSON string holding one option value
"\"US_PHYSICIAN\""
NUMBER
A bare number
"3"
DOCUMENT
Optional uploads, not covered by this guide
n/a
Shipments with more than one line
Each item gets its own line, so a shipment with two drugs has two. Send one questionnaireAnswersSubmit per line, aliased, in the same request. The last one to finish returns the session as COMPLETED.
Request: two lines, one HTTP call
1
2
3
4
5
6
7
8
9
10
11
12
13
# One shipment with two drugs: one US_FDA line per item.
mutation SubmitShipment {
firstDrug: questionnaireAnswersSubmit(input: {
sessionId: "questionnaire_session_0rv8xh6y3xpbm"
lineId: "<lines[0].id>"
answers: [ { questionCode: "fda_recipient_us_person", value: "true" }, ... ]
}) { status }
secondDrug: questionnaireAnswersSubmit(input: {
sessionId: "questionnaire_session_0rv8xh6y3xpbm"
lineId: "<lines[1].id>"
answers: [ { questionCode: "fda_recipient_us_person", value: "true" }, ... ]
}) { status }
}
Which questions you get depends on the product's catalog answers (prescription or over-the-counter) and on the patient. All of them are ITEM scope, answered per shipment.
Prescription drug, patient is a US citizen or permanent resident
Required: 8 answers with a US prescriber, or 6 when the treatment began abroad (no physician questions).
questionCode↕
answerType↕
Required↕
Prompt shown↕
What to send↕
Sample value↕
fda_recipient_us_person
BOOLEAN
Required
Is the person receiving this medication a US citizen or permanent resident?
Patient residency. US citizen or permanent resident: true.
true
fda_pip_treatment_basis
SINGLE_SELECT
Required
Who is looking after this treatment?
Prescriber. US-licensed prescriber: US_PHYSICIAN. Treatment started abroad with no US prescriber: BEGUN_ABROAD.
"US_PHYSICIAN"
fda_pip_physician_name
TEXT
Required if US_PHYSICIAN
What is the doctor's full name?
Prescriber full name.
"Dr. Maria Alvarez"
fda_pip_physician_address
TEXT
Required if US_PHYSICIAN
What is the doctor's address?
Prescriber practice address: street, city, state, ZIP.
"975 S Tech Ridge Dr, St George, UT 84770"
fda_recipient_name
TEXT
Required
What is the full name of the person making this certification?
Patient, or the person certifying on their behalf.
"Jane Doe"
fda_recipient_phone
TEXT
Required
What is the certifier's phone number?
Certifier phone, E.164 recommended.
"+14355550100"
fda_recipient_email
TEXT
Required
What is the certifier's email address?
Certifier email.
"jane.doe@example.com"
fda_pip_resident_attest
CHECKBOX
Required
I attest … serious medical condition; not an unreasonable risk; no more than a 3-month supply … (the full statement is shown with the question)
Only true when the patient (or certifier) actually agreed to this statement.
true
Prescription drug, patient is visiting the US
Required: 5 answers. The treatment-basis, physician and resident questions do not apply.
questionCode↕
answerType↕
Required↕
Prompt shown↕
What to send↕
Sample value↕
fda_recipient_us_person
BOOLEAN
Required
Is the person receiving this medication a US citizen or permanent resident?
Patient is in the US temporarily (visiting, studying, working): false.
false
fda_recipient_name
TEXT
Required
What is the full name of the person making this certification?
Patient, or the person certifying on their behalf.
"Jane Doe"
fda_recipient_phone
TEXT
Required
What is the certifier's phone number?
Certifier phone.
"+14355550100"
fda_recipient_email
TEXT
Required
What is the certifier's email address?
Certifier email.
"jane.doe@example.com"
fda_pip_visitor_attest
CHECKBOX
Required
I attest … for a foreign national visiting the United States; no more than a 90-day supply … (the full statement is shown with the question)
Only true when the certifier agreed to this statement.
true
fda_recipient_passport
DOCUMENT
Optional
A copy of their passport or visa
Optional upload. Not needed to complete.
n/a
fda_recipient_prescription
DOCUMENT
Optional
A copy of the prescription, or a letter from the doctor
Optional upload. Not needed to complete.
n/a
Over-the-counter drug
Required: 4 answers. There is no residency question.
questionCode↕
answerType↕
Required↕
Prompt shown↕
What to send↕
Sample value↕
fda_recipient_name
TEXT
Required
What is the full name of the person making this certification?
Patient, or the person certifying on their behalf.
"Jane Doe"
fda_recipient_phone
TEXT
Required
What is the certifier's phone number?
Certifier phone.
"+14355550100"
fda_recipient_email
TEXT
Required
What is the certifier's email address?
Certifier email.
"jane.doe@example.com"
fda_pip_otc_attest
CHECKBOX
Required
I attest … not for treatment of a serious condition; no known significant health risk; no more than a 3-month supply … (the full statement is shown with the question)
Only true when the certifier agreed to this statement.
true
fda_pip_letter
DOCUMENT
Optional
A letter confirming the medication is for personal use
Optional upload. Not needed to complete.
n/a
Recipient name, phone and email always go together in the same submit call. They are stored as one person.
Use your TEST credential to fire a real test webhook at your registered TEST URL. It opens a real session for one of your catalogued products, so you can run steps 2 to 4 end to end. Test sessions are never filed with customs.
Request
POST https://api.zonos.com/graphql
Content-Type: application/json
credentialToken: <your TEST credential>
mutation {
webhookTestSend(input: {
type: COMPLIANCE_COLLECT_REQUEST
complianceCollectRequest: { catalogItemId: "catalog_item_0rva0tsp86xqq" }
}) {
referenceId
type
}
}
Recipient name, phone or email sent without the other two
The certifier's phone number, email address must be supplied with the rest of their details (fda_recipient_phone, fda_recipient_email): they are recorded as one party, not as separate answers.
Always send all three together.
webhookTestSend
Type has no test support
Test webhooks are not supported for type ORDER_CREATED
Use COMPLIANCE_COLLECT_REQUEST.
webhookTestSend
Called with a LIVE credential
Test webhooks can only be sent with a TEST-mode credential
Use your TEST credential.
webhookTestSend
No enabled TEST webhook registered
Register an enabled TEST-mode webhook of type COMPLIANCE_COLLECT_REQUEST before sending a test
Run webhookCreate with your TEST credential first.
webhookTestSend
catalogItemId missing
complianceCollectRequest.catalogItemId is required for COMPLIANCE_COLLECT_REQUEST
Pass the catalog item ID.
webhookTestSend
Catalog item has nothing left to ask per shipment
Catalog item <id> has no open per-shipment compliance questions to test
Pick a catalog item that needs per-shipment answers, such as a prescription drug.
Answer compliance questions via API
Answer compliance questions via API
For pharmacies: get a webhook when a shipment needs FDA personal-import answers, read what is open, and submit everything in one call. Samples use example names and contact details.
When this starts. You can register and test your webhook today, so you are ready for January 20, 2027, when Type 13 entries are required. Zonos uses webhooks to obtain this information when making Type 13 entries. We are also testing this flow with a few shippers. If you would like to take part, contact support@zonos.com or your Zonos rep.
How it works
When one of your shipments needs per-shipment compliance answers, Zonos sends your server a webhook with a session ID. You read that session once and submit every answer in one call.
COMPLIANCE_COLLECT_REQUESTwebhook once per environment.{eventType, sessionId}to your URL.questionnaireAnswersSubmitper line.Before you go live
https://api.zonos.com/graphqlwith your credential in thecredentialTokenheader.WEBHOOK_WRITE(register and test),COMPLIANCE_READ(read sessions) andCOMPLIANCE_WRITE(submit answers).1. Register your webhook
Do this once with your LIVE credential and once with your TEST credential. Store the returned
secreton your server: it signs every delivery. Zonos generates it, and it cannot be set or rotated. If you lose it, read it again withwebhook(id: "<id>") { secret }.Request
Response
{ "data": { "webhookCreate": { "id": "webhook_e3ecd323-1939-485f-9eea-5de47175c2a0", "type": "COMPLIANCE_COLLECT_REQUEST", "status": "ENABLED", "url": "https://pharmacy.example.com/zonos/compliance", "mode": "TEST", "secret": "YOUR_WEBHOOK_SECRET" } } }idmodesecretzonos-signatureheader.url2. Receive the webhook
Zonos sends one POST per shipment session that needs answers. Respond with any 2xx quickly and do the work afterwards.
Delivery to your URL
eventTypeCOMPLIANCE_COLLECT_REQUESTfor this webhook.sessionIdzonos-signaturetimestamp=<ms>,hmac=<base64>. Verify the hmac before trusting the body.checksumzonos-signature.Verify the signature
hmacvalue from thezonos-signatureheader.secret, and Base64-encode it.Hash the body exactly as it arrived. Parsing the JSON and re-serializing it changes the bytes, and the hash will not match. The
timestampis the send time in milliseconds but is not part of the signed data, so do not rely on it to block replays.Verify the signature (Node.js / Express)
import crypto from "node:crypto"; import express from "express"; const app = express(); // express.raw keeps the body as the exact bytes Zonos signed. app.post("/zonos/compliance", express.raw({ type: "application/json" }), (req, res) => { if (!isFromZonos(req.body, req.get("zonos-signature"), process.env.ZONOS_WEBHOOK_SECRET)) { return res.sendStatus(401); } res.sendStatus(200); const { sessionId } = JSON.parse(req.body); // Queue sessionId for steps 3 and 4. }); function isFromZonos(rawBody, signatureHeader = "", webhookSecret) { // signatureHeader looks like "timestamp=1791327122874,hmac=G/yrP1..." const received = signatureHeader.split(",").find(part => part.startsWith("hmac="))?.slice(5) ?? ""; const expected = crypto.createHmac("sha256", webhookSecret).update(rawBody).digest("base64"); // timingSafeEqual throws on unequal lengths, so check length first. return received.length === expected.length && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected)); }3. Read the session
One query tells you what is open. Each line is one program (such as
US_FDA) for one item, and you answer each line separately.Request
Response: prescription drug, US resident
{ "data": { "questionnaireSession": { "status": "IN_PROGRESS", "containerType": "CONSIGNMENT", "containerId": "consignment_0rv8xh4vhdsem", "lines": [ { "id": "questionnaire_session_line_0rv8xh6ybxpby", "status": "IN_PROGRESS", "targetType": "ITEM", "answerScopes": [ "ITEM" ], "program": { "name": "US_FDA" }, "currentQuestion": { "code": "fda_pip_treatment_basis", "answerType": "SINGLE_SELECT", "answerScope": "ITEM", "prompt": "Who is looking after this treatment?" }, "visibleQuestions": [ { "question": { "code": "fda_recipient_us_person", "answerType": "BOOLEAN", "answerScope": "ITEM", "requirement": "REQUIRED", "prompt": "Is the person receiving this medication a US citizen or permanent resident?", "options": [] }, "answer": { "value": "true" } }, { "question": { "code": "fda_pip_treatment_basis", "answerType": "SINGLE_SELECT", "answerScope": "ITEM", "requirement": "REQUIRED", "prompt": "Who is looking after this treatment?", "options": [ { "value": "US_PHYSICIAN", "label": "A doctor licensed in the United States" }, { "value": "BEGUN_ABROAD", "label": "No US doctor — this continues a treatment started in another country" } ] }, "answer": null }, { "question": { "code": "fda_recipient_name", "answerType": "TEXT", "answerScope": "ITEM", "requirement": "REQUIRED", "prompt": "What is the full name of the person making this certification?", "options": [] }, "answer": null }, { "question": { "code": "fda_recipient_phone", "answerType": "TEXT", "answerScope": "ITEM", "requirement": "REQUIRED", "prompt": "What is the certifier's phone number?", "options": [] }, "answer": null }, { "question": { "code": "fda_recipient_email", "answerType": "TEXT", "answerScope": "ITEM", "requirement": "REQUIRED", "prompt": "What is the certifier's email address?", "options": [] }, "answer": null }, { "question": { "code": "fda_pip_resident_attest", "answerType": "CHECKBOX", "answerScope": "ITEM", "requirement": "REQUIRED", "prompt": "I attest that the following is true and correct to the best of my knowledge and belief: …", "options": [] }, "answer": null } ] } ] } } }statuscontainerIdlines[].idlineIdwhen submitting.lines[].program.nameUS_FDA.lines[].statuslines[].visibleQuestions[].question.codequestionCode. See the question reference.lines[].visibleQuestions[].question.answerTypevalue.lines[].visibleQuestions[].question.options[].valuelines[].visibleQuestions[].answerFollow-up questions are not listed until they apply. The physician name and address only become visible after
fda_pip_treatment_basisisUS_PHYSICIAN. Send them anyway in the same call. Zonos accepts answers to follow-ups that your own answers unlock.4. Submit all answers
Send every answer for a line in one call. The response tells you whether the line, and the whole session, is done.
Request
Response: done
{ "data": { "questionnaireAnswersSubmit": { "status": "COMPLETED", "lines": [ { "id": "questionnaire_session_line_0rv8xh6ybxpby", "status": "COMPLETED", "currentQuestion": null } ] } } }Response: something still missing
{ "data": { "questionnaireAnswersSubmit": { "status": "IN_PROGRESS", "lines": [ { "id": "questionnaire_session_line_0rv8xh6ybxpby", "status": "IN_PROGRESS", "currentQuestion": { "code": "fda_pip_resident_attest" } } ] } } }input.sessionIdinput.lineIdlines[].idin step 3.input.answers[].questionCodeinput.answers[].valuestatuslines[].currentQuestion.codeEncoding
valuetrueorfalse, unquoted"true"truewhen ticked, unquoted"true""\"Jane Doe\""value"\"US_PHYSICIAN\"""3"Shipments with more than one line
Each item gets its own line, so a shipment with two drugs has two. Send one
questionnaireAnswersSubmitper line, aliased, in the same request. The last one to finish returns the session as COMPLETED.Request: two lines, one HTTP call
Question reference: drugs
Which questions you get depends on the product's catalog answers (prescription or over-the-counter) and on the patient. All of them are
ITEMscope, answered per shipment.Prescription drug, patient is a US citizen or permanent resident
Required: 8 answers with a US prescriber, or 6 when the treatment began abroad (no physician questions).
fda_recipient_us_persontruefda_pip_treatment_basis"US_PHYSICIAN"fda_pip_physician_name"Dr. Maria Alvarez"fda_pip_physician_address"975 S Tech Ridge Dr, St George, UT 84770"fda_recipient_name"Jane Doe"fda_recipient_phone"+14355550100"fda_recipient_email"jane.doe@example.com"fda_pip_resident_attesttruePrescription drug, patient is visiting the US
Required: 5 answers. The treatment-basis, physician and resident questions do not apply.
fda_recipient_us_personfalsefda_recipient_name"Jane Doe"fda_recipient_phone"+14355550100"fda_recipient_email"jane.doe@example.com"fda_pip_visitor_attesttruefda_recipient_passportfda_recipient_prescriptionOver-the-counter drug
Required: 4 answers. There is no residency question.
fda_recipient_name"Jane Doe"fda_recipient_phone"+14355550100"fda_recipient_email"jane.doe@example.com"fda_pip_otc_attesttruefda_pip_letterRecipient name, phone and email always go together in the same submit call. They are stored as one person.
Testing
Use your TEST credential to fire a real test webhook at your registered TEST URL. It opens a real session for one of your catalogued products, so you can run steps 2 to 4 end to end. Test sessions are never filed with customs.
Request
Response
{ "data": { "webhookTestSend": { "referenceId": "questionnaire_session_0rva0ybvxp1gp", "type": "COMPLIANCE_COLLECT_REQUEST" } } }input.typeCOMPLIANCE_COLLECT_REQUEST.input.complianceCollectRequest.catalogItemIdreferenceIdErrors you may see
questionnaireAnswersSubmitwebhookTestSendwebhookTestSendwebhookTestSendwebhookTestSendwebhookTestSendWas this page helpful?