Skip to content
/
Webhooks Guide
Last updated

Webhooks Guide

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

About Webhooks

Webhook Endpoint Requirements

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

Security & Signature Verification

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.

Webhook Notification Payload

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).

Example Payloads

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"
    }
  }'

Create a Webhook

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.

Update a Webhook

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.

Retrieve Webhooks

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.

Update a Webhook Token

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.

Delete a Webhook

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.

Previous page
Next page