New Release: Webhooks for Paid Orders

[openapi-support[bot]]

We're excited to announce the initial release of Webhooks, enabling real-time event notifications starting with our first event: ORDER_PAID. With this release, your app can receive updates the moment something happens on Etsy — no polling required!

What's Included in This Release

Commercial applications can now subscribe to receive a webhook whenever a new paid order is created.

• Real-time paid order event delivery ORDER_PAID -
  Your application can now subscribe to receive notifications when an order is paid.
• Subscription management tools for Developers -
  Create, edit, disable, or delete webhook endpoints directly in the Developer Portal for all your commercial apps.
• Secure , reliable event delivery & monitoring -
  Every webhook includes signature headers and a signing secret so you can verify authenticity and prevent tampering. Etsy automatically retries failed deliveries using exponential backoff, and your webhook dashboard provides visibility into delivery history, payloads, and subscription status.

Full Documentation

Learn how to subscribe to events, verify signatures, and handle webhook deliveries in your application here.
Keep an eye on our Announcements for updates! We'll continue expanding event suport and capabilities over time.
Questions? Contact us at developers@etsy.com.

[emergingdzns]

It would be really helpful if you could provide an example of what an ORDER_PAID payload would look like. Is it a transaction or receipt as shown in the API or is it just be basic data of a receipt id or transaction id, requiring us to still ping the API for the data?

[emergingdzns]

actually, if I'm reading the documentation correctly and looking at the example in the developer portal, all this does it notify us that a particular order has been paid, but provides no data about the order. Frankly, this is not particularly helpful. The biggest advantage of a webhook is reducing the reliance on having to poll the API for transactions, receipts, new listings in a shop, listing changes etc. If all you're providing is the url to to call on the API it will only INCREASE the number of API calls we have to make.

It's WONDERFUL that Etsy is finally building out Webhooks but it seems as though it's not well thought out. Any ORDER_ event should also include the full details about that order, same as if you got it from the API.

[emergingdzns]

Setup a webhook url and got the post and sure enough it's very minimal. The documentation says it's important to verify the signature and all that to ensure we aren't getting altered data. But what's the point if all we are getting is the shop id and a url that we have to use to call the API which requires that the shop id matches the authentication used to call the API. Not sure I understand the point of this.

[cyrilchandelier]

Honestly this is great, thank you Etsy team, I'm super grateful for this new system!

It's already VERY NICE to get a real time signal and avoid polling, it will save a lot of requests for shops that don't get sales that often (if at all); and clearly it's the first event for this new webhook system with hopefully more to come.

Agreed with other commenter that it would be nice to have the entire receipt object sent out as part of the payload though, this would make one less API call.

[emergingdzns]

Has anyone else tried following the instructions and been able to successfully validate the signature? No matter what I do I can't get it to validate with the test webhook that was sent. Their webhook-signature is WAY too short to be match a generated signature from the id, timestamp and content.

[cyrilchandelier]

Check the signature you receive, each signature has a version prefix like "v1," that you need to remove. I did not see it documented, but the signature match works when you remove it.

[emergingdzns]

ahhhh. thanks. I'll try that!

[emergingdzns]

I got closer with that suggestion, but still not quite. Appreciate any insight...

$signing_secret = {redacted};
$signed_content = $request->header('webhook-id') . '.' . // = msg_36ibQqFmDV6yNj3hs93z5sXDO87
                                 $request->header('webhook-timestamp') . '.' . // = 1765492325
                                 $request->getContent(); // = {"event_type":"ORDER_PAID","resource_url":"https://openapi.etsy.com/v3/application/shops/12345/receipts/54321","shop_id":42}
                                 
$signing_secret_decoded = base64_decode($signing_secret);

Now, here is what I am getting...

// using the decoded signing secret per documentation...
echo base64_encode(hash_hmac('sha256', $signing_secret_decoded, $signed_content, true));
// -> x4Yof8fFn1+IbVa2RutmdhhoSBqqQCe6QomkkKqf5qo=

// using the still encoded signing secret...
echo base64_encode(hash_hmac('sha256', $signing_secret, $signed_content, true));
// -> vuR96LCwYC/rMEWS3U8w4HR0k0LQH+WLr9a7ki79A74=

// expected signature from Etsy (minus the "v1,")
// -> VC6XthaB7kH88jJC8PkiPJoBF7yBOkN8CNCUi/ZjIfk=

The lengths are looking right but neither of the two generated signatures match the one from Etsy. I tried removing the hard returns and spacing from the raw body content but still it's not working.

[openapi-support[bot]]

The order of the data and key in your hash_hmac function are reversed.

[emergingdzns]

OMG 🤦 I was paying too much attention to the example that's clearly not in PHP. Good grief. That did it. Thank you!

[axsuul]

Hi we have entered multiple endpoints but haven't received any webhook events from our customers @ https://www.etsy.com/developers/webhooks-consumer-portal/147578205393

We reached out to support but they are not even aware of this feature yet. Can you please look into what we are doing wrong? Thanks

[axsuul]

The API docs are wrong when it describes the event payload. It mentions there is a data attribute but there is no data attribute present in the webhook event. The actual webhook event that's received looks like:

{"event_type":"ORDER_PAID","resource_url":"https://api.etsy.com/v3/application/shops/6675216/receipts/3917482190","shop_id":6675216}

The docs mention there should be event_id and created_at fields but those are missing as well.

[emergingdzns]

I think those are in the headers. The event_id is the webhook-id and the created at is really the webhook-timestamp.

[inforohitwebkul]

Hi @emergingdzns
Hope you are doing well.
Have you completed the signatures match flow?
If you're done, please guide me.

    $data = $request->getContent();
    // ->{"event_type":"ORDER_PAID","resource_url":"https://api.etsy.com/v3/application/shops/10391003/receipts/3950649637","shop_id":10391003}"

    $webhookId        = $request->headers->get('webhook-id'); //msg_38K9Bb8ocu1xhdl0vvmngKCcFmJ
    $webhookTimestamp = $request->headers->get('webhook-timestamp'); //1768537260
    $webhookSignature = $request->headers->get('webhook-signature'); // v1,alDx+cHNPQo+LTnB1sLmT05NC7MJtz6hZ7BxIkFX84E=

    $webhookSecret = 'whsec_xxxxxxxxxxxxxxxxxxx';
    $secretBase64 = explode('_', $webhookSecret)[1]; // HaPTK1UMPvR4sk8ciq0IG9fdgfdgg
    $secretBytes = base64_decode($secretBase64); 
   
    $signedContent = $webhookId . "." . $webhookTimestamp . "." . $data;
    $expectedSignature = base64_encode(hash_hmac('sha256', $signedContent, $secretBytes, true));
    // -> TTd/cSfU7wELa3rrde17egvzuBVP7Md2/BmaBXLwhb4=
    
    $receivedSignature = explode(',', $webhookSignature)[1] ?? ' ';
    // -> alDx+cHNPQo+LTnB1sLmT05NC7MJtz6hZ7BxIkFX84E=

I am getting a different $expectedSignature. I am using PHP. Thank you in advance!

[nabilW]

Hi @inforohitwebkul 👋

I found the issue! The problem is with how you're getting the raw request body. Here's the corrected code:

// Get RAW body (important!)
$data = $request->getContent();

$webhookId        = $request->headers->get('webhook-id');
$webhookTimestamp = $request->headers->get('webhook-timestamp');
$webhookSignature = $request->headers->get('webhook-signature');

$webhookSecret = 'whsec_XXXXXXXXXXXXX'; // Use your actual secret
$secretBase64 = explode('_', $webhookSecret)[1];
$secretBytes = base64_decode($secretBase64);

// Build signed content - must match Etsy's format exactly
$signedContent = $webhookId . "." . $webhookTimestamp . "." . $data;

// Generate expected signature
$expectedSignature = base64_encode(hash_hmac('sha256', $signedContent, $secretBytes, true));

// Extract v1 signature from header
$receivedSignature = explode(',', $webhookSignature)[1] ?? '';

// Compare signatures
if (hash_equals($expectedSignature, $receivedSignature)) {
    // ✅ Valid webhook!
    $payload = json_decode($data, true);
    // Process your order...
} else {
    // ❌ Invalid signature
    http_response_code(401);
    exit('Invalid signature');
}

Key points:

1. ✅ Use $request->getContent() to get the raw body (not parsed)
2. ✅ The signed content format is: {webhook-id}.{webhook-timestamp}.{raw-body}
3. ✅ Use hash_equals() for timing-safe comparison
4. ✅ Make sure you regenerated your webhook secret after it was exposed

Debugging tips:
If it still doesn't match, add this debug code (remove after testing):

error_log("Expected: " . $expectedSignature);
error_log("Received: " . $receivedSignature);
error_log("Signed Content: " . $signedContent);
error_log("Raw Body Length: " . strlen($data));

Let me know if this works! 🎯

[nabilW]

Hi @inforohitwebkul 👋

⚠️ URGENT SECURITY ISSUE: You've publicly exposed your webhook secret (whsec_HaPTK1UMPvR4sk8ciq0IG9fdgfdgg) in your code example above. Please:

1. Immediately regenerate your webhook secret in the Etsy Developer Portal
2. Edit your comment above to remove or redact the secret key
3. Never share webhook secrets, API keys, or any credentials in public forums

Anyone with this secret can forge webhook requests to your endpoint, which is a serious security risk.

---

Regarding your signature verification issue:

Your code looks mostly correct, but based on other discussions in this thread, here are some things to verify:

1. Check the signature format - Make sure you're properly stripping the v1, prefix from the signature header
2. Verify your secret decoding - The secret should be base64-decoded correctly
3. Confirm the signed content format - It should be exactly: {webhook-id}.{webhook-timestamp}.{raw-body}

Your code structure looks good. Once you regenerate your secret and update it, try this again. If you're still having issues, you can share your code again (but never include the actual secret - use a placeholder like 'whsec_XXXXXXXXXXXX' instead).

Good luck! 🔐

[mateusztumatek]

Hi Etsy Developer Team

Thank you very much for introducing webhooks. We really appreciate this step forward.

We wanted to ask whether you have plans to add more webhooks in the future.
At the moment, we’re working on integrating our application with your system, and we frequently rely on polling for products, inventory levels, and orders along with their statuses.

Are there any plans to introduce webhooks for these areas? If so, do you have an approximate timeline for when they might become available?

Thanks in advance for any information you can share.

Best regards,

[inforohitwebkul]

Hi @nabilW
Yes, now the $expectedSignature and $receivedSignature are matching. Earlier, the mismatch was due to an incorrect webhook secret being defined in the code. I have now updated it with the correct webhook secret.

Thank you!

Best regards,