Where is Webhooks response values documentation

[synconnv1]

I am working on implementing the webhooks method of response on a payment, but cannot find a list of all the possible values that are returned from the notification and what they represent. 

The sample in the webhooks docs I can find only show a few values like: 

{
"notificationId": "d0e8e7fe-c3e7-4add-a480-27bc5ce28a18",
"eventType": "net.authorize.payment.authcapture.created",
"eventDate": "2017-03-29T20:48:02.0080095Z",
"webhookId": "63d6fea2-aa13-4b1d-a204-f5fbc15942b7",
"payload": {
"responseCode": 1,
"authCode": "LZ6I19",
"avsResponse": "Y",
"authAmount": 45.00,
"entityName": "transaction",
"id": "60020981676"
}
}

The doc does not say anything about all values that are available or what the ones listed mean (i.e. what "id" values is being sent back.)

Any help on getting complete information on this would be really appreciated.

Thanks,

Ed

[Aaron]

Hi @synconnv1,

For starters, I assume you're talking about the docs here, correct?

There's a section in there called "New API Fields in the Payload". That section spells out that every object name that could be returned in the payload is as defined in our API Reference Guide, with two exceptions: the "entityName" and the "id".

The "id" is going to be one of four things, and what it is depends on the "entityName". Think of the "entityName" as sort of a prefix for the "id". For example, if the "entityName" is "transaction", the "id" value represents a transaction ID.

We'll look into ways of spelling that out more clearly in the docs. As far as the stuff outside the "payload" object goes, those are either the same thing that you sent in a request, or something that you can hopfully figure out from context (like "eventDate" is the time stamp that the event occurred that it's notifying you about).

I'm hoping we can refine this in the future to include at least a table of accepted fields in the requests and possible fields in the response. For now, the sample requests indicate everything that you can send, and the sample responses indicate everything possible that you would receive back, with one exception: When creating or updating a Webhook, you can designate a "name" value to help you keep it straight, and that "name" would be returned in responses relating to the Webhook itself. That field is included in the next rev of the docs that should be live within a couple of days.

[linvio]

I'd like to follow up on this question to see if you guys have produced any documentation to list all possible values for webhook notification payloads.  The documentation suggests that the examples are relatively complete, but also seem to indicate that AuthNet *might* at some point include any number of the API call response values documented in the API reference.  I understand that AuthNet expects developers to use the getDetails API to ... well get more details, so I'm guessing the intention is to keep the information provided in the webhooks fairly sparse.

Our development platform requires that we define the values being parsed from the payload JSON notification in a global class before releasing the product to our customers.  So if we leave one out, we have a major headache to deal with.  On the other hand, if we include every possible API response value that's getting a little out of hand.

It would be nice to know what values we can expect in the payload (and their types) and not have to guess.

Cheers,

Ron

[Anurag]

Hi 

The payloads defined at https://developer.authorize.net/api/reference/features/webhooks.html#Event_Types_and_Payloads   are the correct and kept updated . 

For any future updates in payload fields  they will be kept   backward compatible and the documentation will be updated along with a blog post with the changes . 

Hope it helps !!

Thanks

[linvio]

Hi -

Thanks for the reply ... that's not quite the answer I was hoping for.  In the documentation you reference....

"Although most of the fields in an event notification's payload use standard Authorize.Net API fields, which are documented in our API Reference, there are two new fields"

This suggests that we can expect any of the fields documented in the API Reference in a webhook notification ... but I have my doubts that this is what was meant.  

Should I assume that the fields shown in the examples on this page are the complete set of fields we can expect in each webhook notification?

Also, it would be nice to have a webhooks version number we can configure in our customers'  merchant accounts.  If AuthNet adds a new field to one of the webhooks, the JSON parser on our platform will fail (not having a field to map the new value to) and customers will stop getting notifications until a new version of our product can be released, installed and configured in each customers org.  (Practically speaking, this could take weeks)  But if we can select the webhooks version in a merchant account, we can manage upgrades without having the solution break.  

Is webhooks version control in your plan?

Thanks

[Aaron_Actual]

---

"Although most of the fields in an event notification's payload use standard Authorize.Net API fields, which are documented in our API Reference, there are two new fields"

---

I think you're reading something into this sentence that's not quite there. Let me try to restate that sentence more explicitly:

"Following is a set of example payloads for each of the event notifications that might be received. In each example, you'll see all the fields listed that would you expect to receive in a payload for this notification. Every field returned in the payload object maps to the corresponding field in our API Reference, so we're not going to bother to document those fields here. If you want more information about a specific field, you can check the API Reference and look for that field name to find out more. However, there are two fields that you'll see in the payload object in the examples that aren't used elsewhere in the API, so won't be defined in the API reference. Those are entityName and id, and since they're not documented elsewhere, we'll explain them here..."

There's surely a more concise way to word that, but I'll leave that to the professional tech writers at Authorize.Net. But, to recap, what you see in the payload example is what you'd expect to get from the live system as of the time the documentation was last updated.

To recap what Anurag said, when there's a change, it would be done in a backward compatible manner (meaning probably adding a field not previously there, not redfining a field already existing in the payload to mean something different. Also, documentation would be updated to reflect the change. Those are reasonable to expect.

What you are likely not going to get, though, is some sort of advance notification like "In 90 days, field xxxxxx will be added to the payload in a notification for event yyyyyy". More likely, the system will be changed, and then the documentation will be changed to reflect the new operation. So, if the way your software works depends on getting that kind of advance change notification, you'd better rethink the way your software works.

---

Also, it would be nice to have a webhooks version number we can configure in our customers'  merchant accounts.  If AuthNet adds a new field to one of the webhooks, the JSON parser on our platform will fail (not having a field to map the new value to) and customers will stop getting notifications until a new version of our product can be released, installed and configured in each customers org.  (Practically speaking, this could take weeks)  But if we can select the webhooks version in a merchant account, we can manage upgrades without having the solution break.  

Is webhooks version control in your plan?

---

I'm not affiliated with Authorize.Net, nor do I have any special insight into their development plans, but I can almost promise you that that won't happen. That's a complex and cumbersome undertaking that would help almost no one.

There's nothing in the JSON spec or RFC that requires an implementation to ignore unexpected or undefined JSON name/value pairs, but what you're doing certainly seems against the spirit of things like JSON. It seems like developers are flocking to JSON and demanding its use because using it is simple and... well... pleasurable compared to using rigid, versioned, ordered formatting of old.

Is there any good reason why you can't just ignore a unkown name/value in a JSON object?

[Aaron_Actual]

Let it be known that it's the community software that messed up the formatting in the prior post, not me. Apparently, users are only given 15 minutes to edit their posts as well. What follows is a correctly formatted version:

---

"Although most of the fields in an event notification's payload use standard Authorize.Net API fields, which are documented in our API Reference, there are two new fields"

---

I think you're reading something into this sentence that's not quite there. Let me try to restate that sentence more explicitly:

"Following is a set of example payloads for each of the event notifications that might be received. In each example, you'll see all the fields listed that would you expect to receive in a payload for this notification. Every field returned in the payload object maps to the corresponding field in our API Reference, so we're not going to bother to document those fields here. If you want more information about a specific field, you can check the API Reference and look for that field name to find out more. However, there are two fields that you'll see in the payload object in the examples that aren't used elsewhere in the API, so won't be defined in the API reference. Those are entityName and id, and since they're not documented elsewhere, we'll explain them here..."

There's surely a more concise way to word that, but I'll leave that to the professional tech writers at Authorize.Net. But, to recap, what you see in the payload example is what you'd expect to get from the live system as of the time the documentation was last updated.

To recap what Anurag said, when there's a change, it would be done in a backward compatible manner (meaning, for example, they'd make changes by adding a field not previously there, not redfining a field already existing in the payload to mean something different). Also, documentation would be updated to reflect the change. Those are reasonable things to expect.

What you are likely not going to get, though, is some sort of advance notification like "In 90 days, field xxxxxx will be added to the payload in a notification for event yyyyyy". More likely, the system would be changed to send a new field, and then shortly thereafter the documentation would be changed to reflect the new behavior. So, if the way your software works depends on getting that kind of advance change notification, you'd better rethink the way your software works.

---

Also, it would be nice to have a webhooks version number we can configure in our customers' merchant accounts. If AuthNet adds a new field to one of the webhooks, the JSON parser on our platform will fail (not having a field to map the new value to) and customers will stop getting notifications until a new version of our product can be released, installed and configured in each customers org. (Practically speaking, this could take weeks) But if we can select the webhooks version in a merchant account, we can manage upgrades without having the solution break.

Is webhooks version control in your plan?

---

I'm not affiliated with Authorize.Net, nor do I have any special insight into their development plans, but I can almost promise you that that won't happen. That's a complex and cumbersome undertaking that would help almost no one.

There's nothing in the JSON spec or RFC that requires an implementation to ignore unexpected or undefined JSON name/value pairs, but what you're doing certainly seems against the spirit of things like JSON. It seems like developers are flocking to JSON and demanding its use because using it is simple and... well... pleasurable compared to using rigid, versioned, ordered formatting of old.

Is there any good reason why you can't just ignore a unknown name/value in a JSON object? I know next to nothing about Salesforce development, so is this something they require?

[akagarwa]

Hi 

I believe that your concern can be handled with this official SF documentation here

Note the statement:Usage

If the JSON content contains attributes not present in the System.Type argument, such as a missing field or object, deserialization fails in some circumstances. When deserializing JSON content into a custom object or an sObject using Salesforce API version 34.0 or earlier, this method throws a runtime exception when passed extraneous attributes. When deserializing JSON content into an Apex class in any API version, or into an object in API version 35.0 or later, no exception is thrown. When no exception is thrown, this method ignores extraneous attributes and parses the rest of the JSON content.

Hope this helps.

[linvio]

Thanks for the clarification, and the suggestions.  Indeed, Salesforce's JSON.deserialize method is forgiving of extraneous attributes.  I was originally relying on the automatic deserialization that Salesforce does to populate the parameters of the Post handler - however with this approach a JSON parsing error is thrown if the attributes don't match up. 

I found in the documentation that you can pull the webhook values from request body instead and use the JSON class methods to deserialize the body. 

https://salesforce.stackexchange.com/questions/15578/restrequest-requestbody-instead-of-params

It looks like that will solve the problem.

Thanks, again!

[brameshatos]

Hi,

We are using SIM payment form to do credit card payment, that is redirecting to authorize.net payment form from our application.

And authorize.net send the response to relay url.

Now we are planning to change to  webhooks to do credit card payment, we need to implement the webhook without changing  the above flow.

Because we don’t want to enter store or enter credit card information in our system.

I am trying to create same using below steps

1)Register event types and url which need to post the notification to that url

    event types have registered using serive url https://apitest.authorize.net/rest/v1/webhooks

: net.authorize.payment.authcapture.created 

2)Doing payment using SIM payment form and credit card done success(authorized and captured) for this event i should get notification on the resgistered url, but i am not getting.

Can you please let us know what is the issue, anything i need to pass while doing payment for identifying the webhook.

and could you please let us know your thoughts and let us know what changes we need to do for this approach.

Thanks & Regards

Ramesh Bolla