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