Webhooks

GunTab can send your app real-time updates about your transactions, so you know when to prepare a shipment, when to ship, and when you've been paid.

What are webhooks?

Webhooks are HTTP POST requests that GunTab makes to the URL of your choice. These requests include a JSON-formatted payload with details about a transaction. These requests occur when GunTab updates a transaction to one of the webhook-enabled transaction statuses.

How do I configure webhooks?

Go to Account > Webhooks to add up to 3 webhook endpoints, and review your existing webhook endpoints. Webhooks will be sent to every endpoint you configure, for every eligible transaction status.

What are the webhook-enabled transaction statuses?

When a transaction enters any one of these statuses, a webhook is sent:

• canceled
• pending_buyer_checkout
• pending_buyer_inspection_period
• pending_disbursement_processing
• pending_buyer_dispute_review
• pending_outbound_shipment
• pending_outbound_shipment_delivery
• pending_payment_processing
• pending_pickup_readiness
• pending_refund_processing
• pending_verifications
• succeeded

What do the JSON payloads look like?

Here is an example JSON payload that would be posted to your webhook endpoint:

{
  "event": "buyer_completed_checkout",
  "invoice_id": "f7a54f6d-d385-4192-9f72-c601de1af8ed",
  "seller_order_id": "55555",
  "status": "pending_outbound_shipment",
  "transaction_id": "d5f74026-256e-4496-8f6f-b4028af07977"
}

The values are defined as follows:

• invoice_id: The GunTab Invoice ID for the transaction.
• seller_order_id: Your order ID for the transaction, which you provided when creating the Invoice.
• status: The new status that the transaction just entered. Details on how to interpret these values can be found below.
• transaction_id: The GunTab ID for the transaction.

Can webhook payloads be verified?

Yes, all webhook payloads are signed so you can verify them. You should use your webhook's "signing secret key" to generate your own HMAC, and compare it to GunTab's HMAC included with each webhook payload. Here's how it works:

• Get your webhook's "signing secret key".
  Go to Account > Webhooks, select a webhook, then click to show the value. It starts with ssk_.
• Get the timestamp and GunTab's HMAC.
  When your app receives a webhook payload from GunTab, get the value of the X-GunTab-Signature-512 header. (It looks like t=1770907131,v=b378bfd9c34d767edbb69da09d8aecdc7f940fc7198705762ab331afdcf725042b3c503ad4b89395ee3869bb44244f2a0ed72c104eba6bf57749b0e9f787df54.) Split the string by comma (,) to get the key-value pairs. The t key represents the Unix timestamp. The v key represents GunTab's HMAC.
• Build your HMAC.
  Build your HMAC using the SHA512 algorithm with hexdigest formatting. For example, in Ruby you should use OpenSSL::HMAC.hexdigest('SHA512', key, data). The "key" is your your webhook's "signing secret key". The "data" is created by concatenating the Unix timestamp, a dot/period character (.), and the JSON string from the webhook payload.
• Compare your HMAC against GunTab's HMAC.
  If the HMAC strings don't match, the webhook payload may not be legitimate.

If verifying the signature exceeds your technical capabilities, there is a simpler but less secure alternative. You can add a token parameter to the endpoint URL you enter in GunTab, with a random value that you generate. Then when you receive a webhook payload from GunTab, you check to confirm the token parameter has the value you generated. If the strings don't match, the webhook payload may not be legitimate.

What is the recommended usage?

We recommend monitoring for at least the following event and status values:

1. event "buyer_completed_checkout": The seller should consider the the merchandise "sold" and prepare it for shipment (but should not send until after payment processing).
2. status "canceled": The transaction was canceled before payment processing. The merchandise should be considered "available for sale".
3. event "payment_processing_succeeded": The seller should consider the merchandise paid for, and should send the shipment then "mark as shipped" in GunTab.
4. status "refunded": The transaction was canceled after payment, so the buyer was refunded. The merchandise should be considered "available for sale" again.
5. status "succeeded": The transaction was completed successfully, and the seller received the disbursement.

What are statuses to beware of?

Be on the lookout for status values that indicate a delay or a problem:

• canceled: The buyer decided not to purchase. This is similar to pending_refund_processing, except the payment was not processed.
• pending_verifications: This occurs after buyer checkout if the buyer needs to verify the payment method, or GunTab needs to manually review the transaction.
• pending_buyer_dispute_review: The buyer disputed the transaction after fulfillment, and GunTab is reviewing.
• pending_seller_inspection_period: The seller muts inspect the returned merchandise within 3 days.
• pending_refund_processing: The merchandise was returned to the seller after the transaction was successfully disputed.
• refunded: There was a problem with the transaction that caused it to be refunded. This is similar to canceled, except the payment was processed.

Can I simulate/test webhooks?

Yes. Go to Account > Webhooks, select a webhook then click the "Test" button. For each test you can select which status you want to POST to your endpoint.

Can I see webhook results?

Yes. Go to Account > Webhooks, select a webhook then see the "last used" information, including:

• Time
• Transaction number
• Transaction status
• Response status your endpoint returned