Webhook documentation isn't clear on status vs event

[cederberg]

The documentation at https://docs.postalserver.io/developer/webhooks specifies "the following statuses may be delivered":

• MessageSent - when a message is successfully delivered to a recipient/endpoint.
• MessageDelayed - when a message's delivery has been delayed. This will be sent each time Postal attempts a delivery and a message is delayed further.
• MessageDeliveryFailed - when a message cannot be delivered.
• MessageHeld - when a message is held.

But when actually testing this, it seems that the actual values sent for the status field are:

• Sent
• SoftFail
• HardFail
• Held

Instead, the values at the top are used in the top-level event field, which is not shown at all in the examples on the page. Think it would be useful and much more clear if a full webhook HTTP POST was shown somewhere on the page:

{
	"event":"MessageSent",
	"timestamp":1740935264.79515,
	"payload": {
		"message":{
			id":10,
			"token":"...",
			"direction":"outgoing",
			"message_id":"...",
			"to":"...",
			"from":"...",
			"subject":"...",
			"timestamp":1740935259.8611999,
			"spam_status":"NotChecked",
			"tag":""
		},
		"status":"Sent",
		"details":"...",
		"output":"250 2.0.0 OK  ...",
		"sent_with_ssl":true,
		"timestamp":1740935264.785198,
		"time":0.5
	},
	"uuid":"62498fda-ffc5-42f9-b23e-cea5274c513a"
}

[willpower232]

I think the difference between the names of the webhook event and the actual status of the message in Postal could probably be made clearer.

You can see in the code how they're associated

https://github.com/postalserver/postal/blob/fd3c7ccdf6dc4ee0a76c9523cbd735159e4b8000/lib/postal/message_db/delivery.rb#L74-L77

and in the UI there are a whole bunch of different options

If you'd like to have a go at changing the wording to make it make more sense then be my guest.