Webhooks - Amplia Reg
You can register a URL to be called (via POST method) on every status transition that occurs for orders created by your application.
See Order statuses for what each status means and how an order moves between them.
Delivery
Amplia Reg sends each notification as a POST request with a JSON body (Content-Type: application/json). Only orders created by
your application trigger notifications to it. Respond with a 2xx status code: any other response, or no response, counts as a failed
delivery.
If you configure a secret for the webhook, Amplia Reg sends it in a header, according to the authentication type chosen:
| Authentication type | Header sent |
|---|---|
Basic | Authorization: Basic <secret> |
Bearer | Authorization: Bearer <secret> |
ApiKey | X-Api-Key: <secret> |
CustomAuthorizationHeader | Authorization: <secret> |
| No authentication | (none) |
The secret is sent exactly as configured. For Basic, configure the Base64 encoding of user:password as the secret. Check the header on every request to make sure the notification came from Amplia Reg.
Events
The type field says which event the notification is about:
type | When it is sent | Payload field |
|---|---|---|
OrderStatusChanged | On every status change of the order, including its creation | orderStatusTransitionModel |
OrderVideoIdentificationCompleted | When the holder finishes the self-service video identification of a video identification order | videoIdentificationCompletedModel |
The payload field of the other event is null.
Status change fields
| Field | Description |
|---|---|
orderId | Order ID |
orderNumber | Order number |
orderSaleNumber | Order number in your sales system, if one was given when the order was created |
previousStatus | Status before the change; null when the order is created |
status | New status. See Order statuses |
date | Date and time of the change |
validationAgent, confirmationAgent | Agents assigned to the order at the time of the change (id, name, identifier, birthDate), or null |
description | Free text entered with the change: the cancellation reason, the agent's explanation when sending the order back, declining it or revoking the certificate, or a note entered when the order was submitted or approved. null if none |
pendencyReason | When status is Pending: why the order was sent back. DataMismatch, TypingError, BadFiles, BryPSBioFraudSuspected, RedoSaf, RedoVideoconference or Other |
declineReason | When status is Declined: why the order was declined. SubjectDataChanged, KeyGenFailed, ExpiredDocuments, OfficialDocumentsMismatch, ExtemporaneousQuery, BryPSBioFraud, BryPSBioDeleted, BryPSBioVideoconferenceEnroll, InternalAuditIrregularIssuance or Other |
revocationReason | When status is Revoked: why the certificate was revoked. RequestedBySubject, ViolationOrImproperUse, JudicialOrder, DeathOrExtinction, ActivityCessation, DiscoveryOfFalsityOrInaccuracyOfData, BryPSBioFraud, BryPSBioDeleted, InternalAuditIrregularIssuance, RevokedBySubject or Other |
reasonDesc | Short label for the reason, required when the reason is Other |
New values may be added to these lists. Treat an unknown value as Other.
Payload examples
note
The examples below are formatted for readability only; JSON is sent without formatting. Every field is always present, with null when
it has no value.
Order created
{
"type": "OrderStatusChanged",
"orderStatusTransitionModel": {
"orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
"orderNumber": "800-005-520",
"orderSaleNumber": null,
"previousStatus": null,
"status": "WaitingValidation",
"date": "2025-03-18T15:26:11.704304+00:00",
"validationAgent": null,
"confirmationAgent": null,
"description": null,
"pendencyReason": null,
"declineReason": null,
"revocationReason": null,
"reasonDesc": null
},
"videoIdentificationCompletedModel": null
}
Order under validation
{
"type": "OrderStatusChanged",
"orderStatusTransitionModel": {
"orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
"orderNumber": "800-005-520",
"orderSaleNumber": null,
"previousStatus": "WaitingValidation",
"status": "InValidation",
"date": "2025-03-18T15:27:28.358558+00:00",
"validationAgent": {
"id": "0bcc8325-7122-4e5d-80b4-720beec03ede",
"name": "John Doe",
"identifier": "16545693050",
"birthDate": "1988-04-01T00:00:00"
},
"confirmationAgent": null,
"description": null,
"pendencyReason": null,
"declineReason": null,
"revocationReason": null,
"reasonDesc": null
},
"videoIdentificationCompletedModel": null
}
Order waiting confirmation
{
"type": "OrderStatusChanged",
"orderStatusTransitionModel": {
"orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
"orderNumber": "800-005-520",
"orderSaleNumber": null,
"previousStatus": "InValidation",
"status": "WaitingConfirmation",
"date": "2025-03-18T15:28:54.772066+00:00",
"validationAgent": {
"id": "0bcc8325-7122-4e5d-80b4-720beec03ede",
"name": "John Doe",
"identifier": "16545693050",
"birthDate": "1988-04-01T00:00:00"
},
"confirmationAgent": null,
"description": null,
"pendencyReason": null,
"declineReason": null,
"revocationReason": null,
"reasonDesc": null
},
"videoIdentificationCompletedModel": null
}
Order under confirmation
{
"type": "OrderStatusChanged",
"orderStatusTransitionModel": {
"orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
"orderNumber": "800-005-520",
"orderSaleNumber": null,
"previousStatus": "WaitingConfirmation",
"status": "InConfirmation",
"date": "2025-03-18T15:29:20.118344+00:00",
"validationAgent": {
"id": "0bcc8325-7122-4e5d-80b4-720beec03ede",
"name": "John Doe",
"identifier": "16545693050",
"birthDate": "1988-04-01T00:00:00"
},
"confirmationAgent": {
"id": "5d2f8a41-93c7-4b0e-a1d6-2f7c9e3b8a10",
"name": "Maria Silva",
"identifier": "52998224725",
"birthDate": "1990-07-12T00:00:00"
},
"description": null,
"pendencyReason": null,
"declineReason": null,
"revocationReason": null,
"reasonDesc": null
},
"videoIdentificationCompletedModel": null
}
Order sent back for correction
The confirmation agent sent the order back to the validation agent. pendencyReason says why, and description carries the agent's explanation.
{
"type": "OrderStatusChanged",
"orderStatusTransitionModel": {
"orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
"orderNumber": "800-005-520",
"orderSaleNumber": null,
"previousStatus": "InConfirmation",
"status": "Pending",
"date": "2025-03-18T15:29:47.502913+00:00",
"validationAgent": {
"id": "0bcc8325-7122-4e5d-80b4-720beec03ede",
"name": "John Doe",
"identifier": "16545693050",
"birthDate": "1988-04-01T00:00:00"
},
"confirmationAgent": {
"id": "5d2f8a41-93c7-4b0e-a1d6-2f7c9e3b8a10",
"name": "Maria Silva",
"identifier": "52998224725",
"birthDate": "1990-07-12T00:00:00"
},
"description": "The photo of the identity document is unreadable. Please upload it again.",
"pendencyReason": "BadFiles",
"declineReason": null,
"revocationReason": null,
"reasonDesc": null
},
"videoIdentificationCompletedModel": null
}
Order approved (waiting issue)
If confirmation is not required, the order goes from InValidation (or WaitingResources) straight to WaitingIssue, and confirmationAgent is null.
{
"type": "OrderStatusChanged",
"orderStatusTransitionModel": {
"orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
"orderNumber": "800-005-520",
"orderSaleNumber": null,
"previousStatus": "InConfirmation",
"status": "WaitingIssue",
"date": "2025-03-18T15:30:14.052941+00:00",
"validationAgent": {
"id": "0bcc8325-7122-4e5d-80b4-720beec03ede",
"name": "John Doe",
"identifier": "16545693050",
"birthDate": "1988-04-01T00:00:00"
},
"confirmationAgent": {
"id": "5d2f8a41-93c7-4b0e-a1d6-2f7c9e3b8a10",
"name": "Maria Silva",
"identifier": "52998224725",
"birthDate": "1990-07-12T00:00:00"
},
"description": null,
"pendencyReason": null,
"declineReason": null,
"revocationReason": null,
"reasonDesc": null
},
"videoIdentificationCompletedModel": null
}
Certificate issued
{
"type": "OrderStatusChanged",
"orderStatusTransitionModel": {
"orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
"orderNumber": "800-005-520",
"orderSaleNumber": null,
"previousStatus": "WaitingIssue",
"status": "Issued",
"date": "2025-03-18T15:35:02.987120+00:00",
"validationAgent": {
"id": "0bcc8325-7122-4e5d-80b4-720beec03ede",
"name": "John Doe",
"identifier": "16545693050",
"birthDate": "1988-04-01T00:00:00"
},
"confirmationAgent": {
"id": "5d2f8a41-93c7-4b0e-a1d6-2f7c9e3b8a10",
"name": "Maria Silva",
"identifier": "52998224725",
"birthDate": "1990-07-12T00:00:00"
},
"description": null,
"pendencyReason": null,
"declineReason": null,
"revocationReason": null,
"reasonDesc": null
},
"videoIdentificationCompletedModel": null
}
Certificate revoked
revocationReason says why the certificate was revoked, and description carries the explanation entered with the revocation.
{
"type": "OrderStatusChanged",
"orderStatusTransitionModel": {
"orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
"orderNumber": "800-005-520",
"orderSaleNumber": null,
"previousStatus": "Issued",
"status": "Revoked",
"date": "2025-03-18T15:52:40.230571+00:00",
"validationAgent": {
"id": "0bcc8325-7122-4e5d-80b4-720beec03ede",
"name": "John Doe",
"identifier": "16545693050",
"birthDate": "1988-04-01T00:00:00"
},
"confirmationAgent": {
"id": "5d2f8a41-93c7-4b0e-a1d6-2f7c9e3b8a10",
"name": "Maria Silva",
"identifier": "52998224725",
"birthDate": "1990-07-12T00:00:00"
},
"description": "Revocation requested by the holder.",
"pendencyReason": null,
"declineReason": null,
"revocationReason": "RequestedBySubject",
"reasonDesc": null
},
"videoIdentificationCompletedModel": null
}
Order declined
declineReason says why the order was declined, and description carries the confirmation agent's explanation.
{
"type": "OrderStatusChanged",
"orderStatusTransitionModel": {
"orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
"orderNumber": "800-005-520",
"orderSaleNumber": null,
"previousStatus": "InConfirmation",
"status": "Declined",
"date": "2025-03-18T15:30:31.774102+00:00",
"validationAgent": {
"id": "0bcc8325-7122-4e5d-80b4-720beec03ede",
"name": "John Doe",
"identifier": "16545693050",
"birthDate": "1988-04-01T00:00:00"
},
"confirmationAgent": {
"id": "5d2f8a41-93c7-4b0e-a1d6-2f7c9e3b8a10",
"name": "Maria Silva",
"identifier": "52998224725",
"birthDate": "1990-07-12T00:00:00"
},
"description": "The holder's identity document expired before the validation.",
"pendencyReason": null,
"declineReason": "ExpiredDocuments",
"revocationReason": null,
"reasonDesc": null
},
"videoIdentificationCompletedModel": null
}
Order canceled
description carries the reason sent in the cancellation request.
{
"type": "OrderStatusChanged",
"orderStatusTransitionModel": {
"orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
"orderNumber": "800-005-520",
"orderSaleNumber": null,
"previousStatus": "WaitingIssue",
"status": "Canceled",
"date": "2025-03-18T15:31:04.346843+00:00",
"validationAgent": {
"id": "0bcc8325-7122-4e5d-80b4-720beec03ede",
"name": "John Doe",
"identifier": "16545693050",
"birthDate": "1988-04-01T00:00:00"
},
"confirmationAgent": {
"id": "5d2f8a41-93c7-4b0e-a1d6-2f7c9e3b8a10",
"name": "Maria Silva",
"identifier": "52998224725",
"birthDate": "1990-07-12T00:00:00"
},
"description": "Cancellation requested by customer",
"pendencyReason": null,
"declineReason": null,
"revocationReason": null,
"reasonDesc": null
},
"videoIdentificationCompletedModel": null
}
Video identification completed
Sent for video identification orders, when the holder finishes recording, together with the OrderStatusChanged notification of the order's move to WaitingValidation. The values come from the video identification service: the ones below are only illustrative.
{
"type": "OrderVideoIdentificationCompleted",
"orderStatusTransitionModel": null,
"videoIdentificationCompletedModel": {
"number": "800-005-520",
"sessionId": "7c1e4b9a-2f3d-4e8a-9b6c-1d2e3f4a5b6c",
"success": true,
"faceLivenessStatus": {
"provider": "<provider>",
"success": true,
"attemptCount": 1
},
"idCaptureStatus": {
"success": true,
"matchedFace": true,
"matchedFaceLevel": 92
},
"recordingStatus": {
"sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"durationMs": 48210.0,
"processed": true,
"framesAnalyzedCount": 120,
"framesAverageMatchLevel": 0.91,
"framesAverageNormalizedMatchLevel": 0.88
},
"idCaptureFields": {
"documentCountry": "BRA",
"documentType": "<document type>",
"fullName": "HOLDER NAME",
"firstName": "HOLDER",
"lastName": "NAME",
"cpf": "07917307000",
"dateOfBirth": "1995-10-15T00:00:00+00:00",
"dateOfIssue": "2021-03-02T00:00:00+00:00",
"dateOfExpiration": "2031-03-01T00:00:00+00:00"
}
}
}