Webhooks

This page describes the webhooks mechanism that Trustap provides for delivering asynchronous updates on the status of different resources.

Overview

When a user creates a resource on Trustap (such as a transaction or listing), this is done via an OAuth2 client. The OAuth2 client used to create the resource is then associated with the resource, and webhooks registered with that client on Trustap will be sent a request whenever an update occurs to the resource. In such a case, the resource is called the "target" resource of the event.

Payload

Here is an example payload that could be passed to a webhook endpoint:

{
    "code": "p2p_tx.joined",
    "user_id": "feb33a87-3917-4538-9260-127c8a6b5232",
    "target_id": "1309",
    "target_preview": {
        "id": 1309,
        "status": "joined",
        "currency": "eur",
        "deposit_pricing": {
            "price": 1234,
            "charge": 78
        },
        "description": "Soccer ticket",
        "skip_remainder": false,
        "created": "2019-12-25T09:00:00.000Z",
        "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
        "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
        "joined": "2019-12-25T10:00:00.000Z"
    },
    "time": "2019-12-25T10:00:00.000Z"
}

The following are the included fields:

code (string): A code that signifies the type of event that occurred to the target resource.
user_id (string): The ID of the user that triggered the event, if the event was triggered by a user. For example, if the buyer submits a payment then the buyer's user ID will be in this field. As such, if this field is present on an event where the target resource is a transaction, then the user ID must match either the seller_id or the buyer_id of the target transaction. This field won't be present if the event was caused by an automated system, such as if the funds were released due to the complaints period ending.
target_id (string): The ID of the target resource. Note that this field is returned as a string for uniformity even though transaction resources use integer IDs (see the example payload, above). In this case the target_id is the string rendering of the integer ID. It is safe to render and parse transaction IDs to and from such strings.
target_preview (string): An optional preview of the target resource for efficiency. If this field is present in the event then it can be used to avoid a request to retrieve the target resource.
time (string): The time at which the event occurred.

Event Codes

This section lists the event codes that are currently supported.

Event codes for online transactions

basic_tx.joined
basic_tx.rejected
basic_tx.cancelled
basic_tx.claimed
basic_tx.listing_transaction_accepted
basic_tx.listing_transaction_rejected
basic_tx.payment_failed
basic_tx.paid
basic_tx.payment_refunded
basic_tx.payment_review_flagged
basic_tx.payment_review_finished
basic_tx.tracking_details_submission_deadline_extended
basic_tx.tracked
basic_tx.delivered
basic_tx.complained
basic_tx.complaint_period_ended
basic_tx.funds_released
basic_tx.funds_refunded

See the online transaction lifecycle page for more details on the sequence in which online transactions go through their different states.

Event codes for face-to-face transactions

p2p_tx.joined
p2p_tx.rejected
p2p_tx.cancelled
p2p_tx.claimed
p2p_tx.deposit_payment_failed
p2p_tx.deposit_paid
p2p_tx.deposit_review_flagged
p2p_tx.deposit_review_finished
p2p_tx.deposit_refunded
p2p_tx.deposit_accepted
p2p_tx.priced
p2p_tx.remainder_skipped
p2p_tx.remainder_paid
p2p_tx.remainder_review_flagged
p2p_tx.remainder_review_finished
p2p_tx.buyer_handover_confirmed
p2p_tx.seller_handover_confirmed
p2p_tx.complained
p2p_tx.funds_released
p2p_tx.funds_refunded

See the face-to-face transaction lifecycle page for more details on the sequence in which face-to-face transactions go through their different states.

Authentication

Requests sent to webhooks will carry a basic authentication header, so the username and password carried by the basic authentication can be used to verify the Trustap API as the source of the request.

Listings

References