Webhooks for Manual Review

A webhook is a mechanism for one application to provide other applications with real-time information. GBG Manual Review can notify an application whenever a transaction is created, reviewed, or completed.

GBG Manual Review provides the following information for use with any webhook:

• Service name, for example, review
• Subscription ID, for example, 9ee7685e-ddd5-4356-b038-d01ba9dbb499
• Transaction ID (also called instance ID), for example, 1a70194c-a932-442c-8c68-242e26a2dfd9
• Review stage (see below)
• Time, in milliseconds, spent waiting for a reviewer, for example, wait_time
• Time, in milliseconds, spent by the reviewer, for example, review_time. Adding this time to wait_time will yield the total time spent waiting for a manual review to complete.

Value	Review Stage	Description
0	UnReviewed	Review request waiting for available reviewer
1	InReview	Review request being reviewed
2	Pass	Reviewer passed the review request
3	Fail	Reviewer failed the review request
4	UnableToDecide	Reviewer unable to decide between passing and failing the review request
5	BadImages	Review request contained one or more bad images
6	NotFound	Transaction for review was either deleted or did not include one or more images

The exact format of the webhook can be customized, including

• The HTTP verb (GET, POST, …)
• The JSON body
• Authorization header(s)
• Arbitrary headers

For the examples below, a simple key-value JSON response body is used.

Posting a transaction for review

When a transaction review request is created, the webhook is triggered with review_stage: UnReviewed.

Request

POST https://eu.review.acuant.net/api/v1/transactions

{
  "SubscriptionId": "9ee7685e-ddd5-4356-b038-d01ba9dbb499",
  "InstanceId": "1a70194c-a932-442c-8c68-242e26a2dfd9",
  "Type": 1
}

Webhook body

{
  "service": "review",
  "subscription_id": "9ee7685e-ddd5-4356-b038-d01ba9dbb499",
  "transaction_id": "1a70194c-a932-442c-8c68-242e26a2dfd9",
  "review_stage": "UnReviewed",
  "review_time": "0",
  "wait_time": "0"
}

Reviewing a transaction

When a reviewer begins the review request, the webhook is triggered with review_stage: InReview.

Webhook body

{
  "service": "review",
  "subscription_id": "9ee7685e-ddd5-4356-b038-d01ba9dbb499",
  "transaction_id": "1a70194c-a932-442c-8c68-242e26a2dfd9",
  "review_stage": "InReview",
  "review_time": "0",
  "wait_time": "515000"
}

Completing a transaction

When a reviewer completes the review request, the webhook is triggered with review_stage: Pass (or other final disposition).

Webhook body

{
  "service": "review",
  "subscription_id": "9ee7685e-ddd5-4356-b038-d01ba9dbb499",
  "transaction_id": "1a70194c-a932-442c-8c68-242e26a2dfd9",
  "review_stage": "Pass",
  "review_time": "654000",
  "wait_time": "3000"
}

Ordering and Eventual Consistency

The timing and ordering of the events generated by GBG Manual Review depends on the availability of manual reviewers and is not guaranteed. Events are guaranteed to be eventually consistent. The following sequence of events might occur during a normal manual review process.

Review stage	Description
UnReviewed	Review request is waiting for an available reviewer.
InReview	Review request is being reviewed.
UnReviewed	Review request was not completed; the reviewer may require additional time and/or consultation to complete the review.
InReview	Review request is being reviewed.
Pass	The reviewer has passed the review request.

The order in which they are delivered to the webhook is not guaranteed - they may arrive in any order. If the webhook cannot deliver the message for any reason, it is lost.

Example

To test a webhook, use a site like webhook.site and curl as shown in the following example. You will receive a unique URL from webhook.site that you can monitor from a browser while posting from an application.

curl \
  -X 'POST' 'https://webhook.site/<your-unique-identifier-here>' \
  -H 'connection: close' \
  -H 'authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
  -H 'content-length: 217' \
  -H 'x-transactionid: 295ce5ff-f9e0-4da8-917a-8b6bca5fd6f0' \
  -H 'x-subscriptionid: 9ee7685e-ddd5-4356-b038-d01ba9dbb499' \
  -H 'content-type: application/json' \
  -H 'accept: application/json, */*;q=0.5' \
  -H 'accept-encoding: gzip, deflate' \
  -H 'user-agent: HTTPie/2.2.0' \
  -H 'host: webhook.site' \
  -d $'{"service": "review", "subscription_id": "9ee7685e-ddd5-4356-b038-d01ba9dbb499", "transaction_id": "295ce5ff-f9e0-4da8-917a-8b6bca5fd6f0", "review_stage": "BadImages", "review_time": "1639000", "wait_time": "1344000"}'