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_inspection_period
• pending_disbursement_processing
• pending_dispute_review
• pending_outbound_shipment
• pending_outbound_shipment_delivery
• pending_payment_processing
• pending_refund_processing
• succeeded

What do the JSON payloads look like?

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

{
  "invoice_id": "d7124f45-4766-4240-a7f1-ccfda83b2ea9",
  "seller_order_id": "55555",
  "status": "pending_outbound_shipment",
  "transaction_id": "4b5f0b94-cabd-440c-8a83-8616beb50ddc"
}

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=1730250762,v=dc7374b6644cfa5bb286f305404389a0121a0ebf47a2b8e8a6d753ac11889c71b594da5560a623f7b1530ceeabc5dfaca0dbbce0062eceeb74b3b9a15bc5b31d.) 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 for a seller?

If you are a seller, we recommend the following usage:

1. pending_payment_processing: Package the order for shipment (but do not send).
2. pending_outbound_shipment: Send the shipment and "mark as shipped" in GunTab.
3. pending_outbound_shipment_delivery: No action necessary, this status is informational. GunTab will notify the buyer of delivery.
4. pending_buyer_inspection_period: Expect your disbursement to be sent in 3 days or less.
5. pending_disbursement_processing: No action necessary, this status is informational. Expect your disbursement to be visible in your online banking in 1-2 business days.
6. succeeded: No action necessary, this status is informational. Your disbursement should be visible in your online banking.

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

• canceled: The buyer decided not to purchase. This is similar to pending_refund_processing, except the merchandise was not shipped.
• pending_dispute_review: The buyer disputed the transaction and GunTab is reviewing.
• pending_seller_inspection_period: Inspect the returned merchandise within 3 days.
• pending_refund_processing: The the shipment was returned to sender after being lost or successfully disputed. This is similar to canceled, except the merchandise was probably shipped.

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