Webhooks¶

Webhooks allow you to build or set up integrations which subscribe to certain events on marktplaats.nl. When one of those events is triggered, we’ll send a HTTP POST payload to the webhook’s configured URL.

If you want to take advantage of this feature please speak to your Marktplaats contact person as it is currently not possible to register a webhook via the api. Though we may add support for this in the future.

Message Delivery Guarantees¶

We currently support At least once delivery. This means that messages are never lost but may be redelivered, under, what should be, very rare circumstances. To guard against this you can de-dupe messages on the consumer end based on the unique event id.

Validating the authenticity of requests¶

HTTP callbacks are signed so that consumers can validate the message’s authenticity. The signature is sent as a request header with the name X-Ecg-Signature. It’s value is a HMAC SHA 256 hex digest of the payload, using a shared secret, that will be provided to you as part of the registration process, as the key. The following example illustrates how to generate a signature using the openssl commandline tools.

echo -n '{"id":"id","eventType":"EventType","created":"2015-01-01T11:00:00.000Z","eventData":{"property":"value"}}' | openssl dgst -sha256 -hmac "s3cr3t"

c21dfb6001c97e8f6a9a47aec57f3e94f6e274928ec5724d0662927f87993f97

Generic Message format¶

Events posted to the webhook’s configured url all take the same form. But the event data and links provided in the request differ by event type.

field	type	constraints	Req	W	U
id	string	–	no	no	no
eventType	string	One of BidPlacedEvent, BidClosedEvent, AsqCreatedEvent, transactionStatusChanged	no	no	no
created	ISO 8601 timestamp	–	no	no	no
eventData	map	–	no	no	no

id

Unique identifier for this event - can be used for de-duping purposes

eventType

Identifies the type of event, currently BidPlacedEvent, BidClosedEvent, AsqCreatedEvent, transactionStatusChanged are supported

created

When the event was created

eventData

Map of fields that describe the event. Different for each event type

BidPlacedEvent¶

The following table lists the event data fields for this event :

field	type	constraints	default	Req	W	U
advertisementItemId	string	–		no	no	no

advertisementItemId

Unique identifier for the advertisement this bid is for

The following table lists the relations for this event :

name	availability	embedded	cardinality
mp:advertisement	always	no	1
mp:bid	always	yes	1

BidClosedEvent¶

The following table lists the event data fields for this event :

field	type	constraints	default	Req	W	U
advertisementItemId	string	–		no	no	no
closedBySeller	boolean	–		no	no	no

advertisementItemId

Unique identifier for the advertisement this bid is for

closedBySeller

True if the bid was closed by the seller

The following table lists the relations for this event :

name	availability	embedded	cardinality
mp:advertisement	always	no	1
mp:bid	always	yes	1

AsqCreatedEvent¶

The following table lists the event data fields for this event :

field	type	constraints	default	Req	W	U
advertisementItemId	string	–		no	no	no
asqMessage	string	–		no	no	no

advertisementItemId

Unique identifier for the advertisement this ‘ask seller question’ is for

asqMessage

The actual message which is send. This is only provided for selected API users.

name	availability	embedded	cardinality
mp:advertisement	always	no	1
mp:asker	always	yes	1

transactionStatusChanged¶

The following table lists the event data fields for this event :

field	type	constraints	Req	W	U
transactionId	int	–	no	no	no
oldStatus	string	–	no	no	no
newStatus	string	–	no	no	no

transactionId

Unique identifier for the transaction for which the status is changed

oldStatus

String representing the previous status of the transaction. One of CREATED, PENDING, EXPIRED, CANCELLED, COMPLETED, FAILED, REFUNDED, CHARGEBACK

newStatus

String representing the current status of the transaction. One of CREATED, PENDING, EXPIRED, CANCELLED, COMPLETED, FAILED, REFUNDED, CHARGEBACK

The following table lists the relations for this event :

name	availability	embedded	cardinality
mp:advertisement-transaction	always	yes	1

CallNotificationEvent¶

The following table lists the event data fields for this event :

field	type	constraints	Req	W	U
start	string	–	no	no	no
duration	string	–	no	no	no
eventType	string	–	no	no	no
fromNumber	string	–	no	no	no
fromNumberArea	string	–	no	no	no
toNumber	string	–	no	no	no
endNumber	string	–	no	no	no
channel	string	–	no	no	no
answered	boolean	–	no	no	no
publisherId	string	–	no	no	no
campaignId	string	–	no	no	no
referrer	string	–	no	no	no
url	string	–	no	no	no
userId	string	–	no	no	no
advertisementId	string	–	no	no	no
callId	string	–	no	no	no
freespeeId	string	–	no	no	no

start

start time of call, UTC, format (ISO8601) yyyy-MM-dd’T’HH:mm:ss.SSSZZ

duration

duration of call in seconds

eventType

type of event 0 = post-call, 1 = textMessage/SMS, 2 = pre-call

fromNumber

callers phone number

fromNumberArea

callers geographical area

toNumber

tracking phone number

endNumber

destination phone number

channel

channel, ex Google SEM

answered

whether call was answered

publisherId

publisher id, if exists

campaignId

campaign id, if exists

referrer

visitor referrer url, if exists

url

visitor url, if exists

userId

marktplaats seller id

advertisementId

advertisement id

callId

Unique call id

freespeeId

Unique Freespee call id

Examples¶

Marktplaats sending an event notification

POST /path/url HTTP/1.1
Host: api.consumer.nl
Content-Type:application/hal+json
User-Agent: Marktplaats Webhooks Processor
X-Ecg-Signature: ba69edb0c8fa3f17d2b47f1edc8d53f3baa422dab250354200cc2528b8ba4dc5

{"_links":{"curies":[{"href":"https://api.marktplaats.nl/docs/v1/rels/{rel}.html","templated":true,"name":"mp"}],"mp:advertisement":{"href":"https://api.marktplaats.nl/v1/advertisements/m2087"}},"_embedded":{"mp:bid":{"_links":{"self":{"href":"https://api.marktplaats.nl/v1/advertisements/m2087/bids/190"},"mp:bidder":{"href":"https://api.marktplaats.nl/v1/users/2640"}},"id":190,"amount":1000,"bidder":{"id":2640,"nickName":"tu-2749237ff9be4d5c8d45c1a7a31"},"placeDate":"2015-01-29T10:30:56.000Z"}},"id":"0e4a7b5c-33b8-4e90-af97-f17365ea5d9f","eventType":"BidPlacedEvent","created":"2015-01-29T10:30:56.490Z","eventData":{"advertisementItemId":"m2087"}}

Example of a transaction changed notification

{
  "_links":{
    "curies":[
      {
        "href":"https://api.marktplaats.test/docs/v1/rels/{rel}.html",
        "templated":true,
        "name":"mp"
      }
    ]
  },
  "_embedded":{
    "mp:advertisement-transaction":{
      "_links":{
        "self":{
          "href":"https://api.marktplaats.test/v1/advertisements/m123456/transactions/123"
        }
      },
      "transactionId":123,
      "buyerId":2,
      "amount":200,
      "shippingCosts":140,
      "status":"COMPLETED"
    }
  },
  "id":"bb7b26cf-e4a8-40bb-8d1b-a1a7f0ba60b2",
  "eventType":"transactionStatusChanged",
  "created":"2015-01-01T12:00:00.321Z",
  "eventData":{
    "transactionId":123,
    "oldStatus":"CREATED",
    "newStatus":"COMPLETED"
  }
}

Example of a asq notification

{
    "_links":{
        "curies":[
            {
                "href":"https://api.marktplaats.test/docs/v1/rels/{rel}.html",
                "templated":true,
                "name":"mp"
            }
        ],
        "mp:advertisement":{
            "href":"https://api.marktplaats.test/v1/advertisements/m12"
        }
    },
    "_embedded":{
        "mp:asker":{
            "_links":{
                "self":{
                    "href":"https://api.marktplaats.test/v1/users/83"
                }
            }
        }
    },
    "id":"ad4a39f2-9bcc-4511-95f5-26d02cb020d2",
    "eventType":"AsqCreatedEvent",
    "created":"2016-02-10T16:08:21.069Z",
    "eventData":{
        "advertisementItemId":"m12",
        "asqMessage":"Example message"
    }
}