Marktplaats / 2dehands / 2ememain API solutions for Lead Management Systems

1 Introduction

This document is an overview of the different solutions we offer for lead management systems (LMSs), how they differ, and how they can be used together.

2 Vocabulary

MP - Marktplaats.nl, our Netherlands platform
TWH - 2dehands.be/2ememain.be, our Belgian platform. Any listings on 2dehands are also available on 2ememain and vice versa, so our API solutions make no difference between them.
Advertisement - An ad or listing placed on MP/TWH.
Buyer - A MP/TWH user who is looking to buy something.
Seller - A MP/TWH user who is advertising their products.
Dealer - A professional seller with a focus on mobility products such as cars.
Lead - the initial interaction of a buyer with a seller.
Chat conversation - A conversation in the MP/TWH chat system. A conversation is uniquely linked to a seller, a buyer and advertisement. A conversation always starts from a lead.
Chat message - Any message within a chat conversation, including the message that came with the initial lead.

3 Overview

We currently offer two different push-based services and one pull-based service:

3.1 Lead delivery webhook service

A push-based service that sends leads to your system. This includes:

Leads that initiate a chat conversation such as “messaging lead” and “bid created lead”.
Call tracking leads. This is when the buyer called or tried to call the seller. It allows the seller to track these cases and follow up if necessary.

3.2 LMS Bidirectional communication API

A (pull-based) chat API.

It allows you to get all MP/TWH conversations of your sellers.
You can also use it to let the sellers send new messages.
It can be used to enable/disable MP/TWH e-mails to the seller for chat messages. Sellers with an LMS connection may not need e-mails as well.
And it is used to subscribe to the Chat Message Webhook service.

3.3 Chat message webhook service

An extension of the Bidirectional Communication API that will push new chat messages to your system, so you don’t need to poll the Bidirectional Communication API all the time.

It is designed to have the same data as the Bidirectional Communication API, but as a push-based system, you cannot use it to send messages. The Bidirectional Communication API is the only way to do this.

3.4 Difference between the Lead Delivery Webhook and Chat Message Webhook.

Both of these services offer webhook functionality. But they have a different purpose, and for the best experience for your customers, we recommend you use both.

The Lead Delivery Webhook has enriched leads. That means we include any relevant information in an easy-to-parse json format. Think of extra information about the buyer and additional requests from the buyer such as trading in their old car. It gives the dealer all the information they need to start the lead followup.
- When more enrichment data becomes available, we will add this to the Lead Delivery Webhook.
- Conversation leads in the Lead Delivery Webhook also contain a conversationId, so you can make an easy connection to our chat services.
- Later messages in the same conversation are not leads.
On the other hand, the Chat Message Webhook service is optimized to get chat messages to you as fast as possible. It does not add any lead enrichment data.
- Once you used the Lead Delivery Webhook data to create the initial lead object in your LMS, you can then add updates to the same object using the Chat Message Webhook. Using the Chat Message Webhook alone is technically possible, since it will notify you of the initial message accompanying a lead, but you won’t get complete lead data this way.

4 Implementation example

You can mix these different solutions however you wish, but here is an example flow that works best in our experience. This is assuming you have already subscribed your customer to all three services.

Listen to the Lead Delivery Webhook, and process incoming leads. You can use our seller data fields to route it immediately to a specific sales agent.
Call the Bidirectional Communication API GET conversation call to get the initial state of the conversation.
Listen to new messages in the chat using the Chat Message Webhook.
Use the Bidirectional Communication API to allow the seller to send replies, as well as mark conversations as read.

Step 2 may not be necessary, but this depends on your implementation. It deals with the theoretical situation where the buyer sends a second message before you had a chance to process their initial lead of step 1. All processing on our side is async, so we do not give guarantees on the specific order you will receive webhook messages in.

5 How to connect

If you have no existing connections to MP/TWH yet, please contact us to discuss the possibilities.

Once the paperwork is done, our technical team will supply you with all information you need to set up your API. After that, to actually connect users, we have the following processes in place:

Bidirectional Communication API: Follow the Obtaining an Access Token for a user flow. The user will need to give permission once, after that you can indefinitely renew their access tokens.
Chat Message Webhook service: Use the configuration endpoint in the Bidirectional Communication API with a valid Bidirectional Communication API access token to subscribe to chat updates for a user.
Lead Delivery Webhook: The old way of doing this was by contacting the Marktplaats/2dehands Zakelijk customer service for every user. As a simpler method, you can now also call the lead-delivery configuration endpoint in the Bidirectional Communication API. If you are still set up for the old way, please contact us for the migration to the new method.

We can give you access to our Sandbox environment for integration testing if necessary.

6 Forward compatibility

It’s essential to be aware of our forward compatibility philosophy regarding JSON payloads:

We can always add new properties to our payloads (even in patch version updates). This should not break your implementation. As this is not always the default behaviour for JSON deserialization frameworks (e.g. Jackson), please double-check that you can deserialize payloads that contain more properties than are stated in the specification.

7 Webhooks implementation details

7.1 Error responses and retries

Your webhook endpoint is required only to reply with one of the HTTP response codes mentioned in the OpenAPI specification.

Generally, we treat response codes as follows:

HTTP 2xx: You received the request correctly, and either processed it or ignored it.
HTTP 5xx: Something is temporarily wrong with your system. We may retry sending the message.
HTTP 4xx: You cannot accept the message no matter what. We cannot retry, and will log this as a bug with your system.
Timeout after 2 seconds: Something is temporarily wrong with your system. We may retry sending the message.

This means:

We expect you to be able to respond within 2 seconds. If your processing takes longer than that please make the processing asynchronous from receiving & responding to the message.
Do NOT use 4xx errors if you receive a request you simply don’t care about. Return a 2xx in that case instead. We may follow up on any 4xx errors with you manually to ensure the stability of our connection.

7.2 Request signatures

Our webhook requests contain a signature that allow you to verify both the identity and integrity of the request - that is, does the request actually come from us, and did you get the complete request without modifications? For more info see cavage http signatures.

If you look into a webhook request, you will find two relevant HTTP headers:

digest: SHA-256=46cf432d88fd959d5955031ce2fe34969409284ee51d4c38e19d3a96333c1454

signature: keyId="leadDeliveryKey",algorithm="RSA",created=1636631099,headers="(request-target) (created) digest",signature="27cb4ddfa2e1ef9b9179372b3a41429921249fa8c40cfc86d4b82a79c502f115eeb48d31d23c14bdfa2cfb59abe26ae30a1cbbe219e807b4599c987e2300936045c550cb434a79ccf74b1bd6f7e6829a2a215c339a35a112af79de47a2c37702b32d72a36596e02c741aadc4aa1f71d69bb7afbbaf3040786eb02a81657d5acb8207e8542667dd17898e5975a7e78257b1bec5b5337797923773683a7b600606f10fc5a87185cacd8653cc7bbd18509dfc86c66235360098ed79a4ff295e39d17219c121de86758b9e44b44e952a70189fb1f090c3addb0d76809ac24cdfec28aaab599d48e595cdc466447b00dad0ccd3d6db8aea9dc7c54eac1dd3021fc093

The digest is simply a SHA-256 digest of the message itself.

The signature http header is a very long header with different “sub-fields”:

keyId: tells you which public key to verify the signature against. We currently have two: leadDeliveryKey for the Lead Delivery Webhook and chatMessagePushKey for the Chat Message Webhook.
algorithm: always RSA.
created: the creation timestamp of this signature.
headers: A list of data headers that are actually signed by the signature, always (request-target) (created) digest.
signature: the message signature itself.

Here is an example on how to manually verify the signature:

Step 1. Collect the signature data headers and combine them into a signature string:

echo "(request-target): post /webhook
(created): 1636631099
digest: SHA-256=46cf432d88fd959d5955031ce2fe34969409284ee51d4c38e19d3a96333c1454" > header.txt

(request-target) is post followed by the target endpoint without the domain name.
(created) is the created timestamp in the signature HTTP header.
digest is the value of the digest HTTP header.

IMPORTANT: The signature string contains a trailing new line. Make sure that the signature string you want to verify contains this trailing line feed (not \crlf).

Step 2. Convert the hex-encoded signature to binary:

echo "27cb4ddfa2e1ef9b9179372b3a41429921249fa8c40cfc86d4b82a79c502f115eeb48d31d23c14bdfa2cfb59abe26ae30a1cbbe219e807b4599c987e2300936045c550cb434a79ccf74b1bd6f7e6829a2a215c339a35a112af79de47a2c37702b32d72a36596e02c741aadc4aa1f71d69bb7afbbaf3040786eb02a81657d5acb8207e8542667dd17898e5975a7e78257b1bec5b5337797923773683a7b600606f10fc5a87185cacd8653cc7bbd18509dfc86c66235360098ed79a4ff295e39d17219c121de86758b9e44b44e952a70189fb1f090c3addb0d76809ac24cdfec28aaab599d48e595cdc466447b00dad0ccd3d6db8aea9dc7c54eac1dd3021fc093" > signature.txt

xxd -r -p signature.txt signature.sha256

Step 3. Verify the signature and integrity of data headers against the public key.

openssl dgst -sha256 -verify key.pub -signature signature.sha256 header.txt

The output of this command should be:

Verified OK

Please ask your technical contact at Marktplaats/2dehands for a copy of the relevant public keys.