Webhooks Guide

This guide provides instructions for managing webhook subscriptions to item-related events in Wallapop.

• The webhook endpoint must accept POST requests.
• It must return a 2xx HTTP status code to confirm successful receipt of notifications.

To ensure the integrity and authenticity of the notifications, each request includes two headers:

• X-Wallapop-Signature: HMAC-SHA256 signature of the payload.
• X-Wallapop-Timestamp: Timestamp in epoch milliseconds.

You must verify the signature using the shared secret that is provided when the webhook is created.

Signature Calculation:

1. Concatenate the JSON payload and the timestamp with a colon (:).
2. Hash the resulting string using HMAC-SHA256 with the shared secret.
3. Compare the generated signature with the X-Wallapop-Signature header to validate authenticity.

The timestamp is updated with every request to prevent replay attacks.

Each notification contains a JSON payload with the following structure:

{
    "id": "$unique_notification_id",
    "type": "$event_name",
    "occurred_on": "$event_timestamp",
    "data": { ... }  // Event-specific information
}

• id: A unique identifier for the notification, which remains the same across retries.
• occurred_on: The timestamp (in epoch milliseconds) of when the event occurred.
• data: Event-specific information (the structure varies based on the event type).

The following examples show the payload structure your endpoint will receive for each type of event. Select an example below to see how the payload structure changes for each event type.

curl -i -X POST \
  https://developers.wallapop.com/integrator/your-webhook-implementation \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "318a05ce-7653-4eeb-9a69-5b425e2edb24",
    "type": "SALE_COMPLETED",
    "occurred_on": 1752820579294,
    "data": {
      "item_id": "9nz0m00eejok"
    }
  }'

To create a new webhook, send a POST request to /webhooks:

curl -i -X POST \
  https://connect.wallapop.com/webhooks \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "string",
    "events": [
      "SALE_COMPLETED"
    ]
  }'

A successful request returns a 201 Created status with the webhook token.

Easily update your webhook by changing the endpoint url and the list of events to which the webhook is subscribed:

curl -i -X PUT \
  https://connect.wallapop.com/webhooks/5d5ae7a4-2d0d-4be1-a5da-b49e3291e5cd \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "string",
    "events": [
      "SALE_COMPLETED"
    ]
  }'

A successful request returns a 204 No Content status.

To view your webhooks, send a GET request to /webhooks.

curl -i -X GET \
  https://connect.wallapop.com/webhooks \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

If successful, you'll get a 200 OK status with a list of your webhooks.

Need to refresh your webhook token? Send a PATCH request to /webhooks/{webhookId}/token, including the webhookId in the path:

curl -i -X PATCH \
  https://connect.wallapop.com/webhooks/5d5ae7a4-2d0d-4be1-a5da-b49e3291e5cd/token \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

You’ll receive a 200 OK status with your new webhook token.

To delete a webhook, send a DELETE request to /webhooks/{webhookId}, including the webhookId in the path:

curl -i -X DELETE \
  https://connect.wallapop.com/webhooks/5d5ae7a4-2d0d-4be1-a5da-b49e3291e5cd \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

A successful request will return a 204 No Content status.