topic Re: Idempotent processing of webhook events in APIs & Integrations

Idempotent processing of webhook events

Jdb8 — Sat, 29 Mar 2025 14:12:50 GMT

Hello,

i was wondering on basis of which fields i can determine that my webhook already received an event so that i can make my consumer idempotent.

It is not clear from the documentation (https://developers.hubspot.com/docs/guides/api/app-management/webhooks). I thought eventId would be sufficient, but the documentations says it is not guaranteerd to be unique. But to what extent? Within a given timeframe, for a given objectId?

eventId: The ID of the event that triggered this notification. This value is not guaranteed to be unique.

So in general, how can we do this?

Re: Idempotent processing of webhook events

Jaycee_Lewis — Mon, 31 Mar 2025 16:47:09 GMT

Hi, @Jdb8 👋 Thanks for your question. I'd like to invite some of our community members who have expertise in this area to the conversation — hey @james-portant @SNigam @zach_threadint how would you solve for this situation?

I assume you could do a bit of extra processing and create a unique identifier by combining multiple fields:

eventId
objectId
subscriptionType
timestamp

but is there a “better” way?

Thanks for taking a look! — Jaycee

Re: Idempotent processing of webhook events

Jdb8 — Wed, 09 Apr 2025 12:42:53 GMT

I need to be sure about the solution, @james-portant @SNigam @zach_threadint can you give verify this?

Re: Idempotent processing of webhook events

Jdb8 — Wed, 16 Apr 2025 08:18:52 GMT

Can someone please answer this question or escalate. We are waiting for this to go live. @Jaycee_Lewis

Re: Idempotent processing of webhook events

Jaycee_Lewis — Wed, 16 Apr 2025 19:49:47 GMT

Hi, @Jdb8 👋 Thanks for your follow-up. I understand you're looking for a definitive answer about webhook event idempotency, and I appreciate that this is blocking your progress.

To clarify, the HubSpot Community is a peer-to-peer support forum where community members help each other based on their experiences. The fact that no other members have responded further likely indicates this is a specialized area where many don't have direct experience to share.

The HubSpot documentation clearly mentions that eventId is not guaranteed to be unique. This lack of specification concerning any timeframe or conditions typically means developers should prepare for the possibility of duplicate eventIds

The workaround I suggested (combiningeventId withobjectId,subscriptionType, andtimestamp to create a composite unique identifier) remains the most reliable approach I'm aware of. Many developers use similar patterns when working with webhook systems that don't guarantee unique event identifiers.

If you need an official clarification beyond what's in the public documentation, I'd recommend:

Testing the behavior in your dev environment
Implementing the composite key approach as a safety measure
If available to you, submitting a ticket through your HubSpot support channel

I hope this helps you move forward with your implementation, and if you discover a solution, please consider sharing it back with the community to help others facing similar challenges.

Best regards,
Jaycee